@mentra/engine 3.2.0-dev.235 → 3.2.0-dev.245

package/build/services/LocalMiniappRuntime.js

@@ -8,6 +8,7 @@
  * This runtime handles request dispatch, stream fan-out, and lifecycle
  * management (connect/disconnect/ping).
  */
+import { parsePhotoCompression } from "@mentra/cloud-protocol/photo-compression";
 import { acquireGlassesHotspot } from "./GlassesHotspotLease";
 import { AppState, Linking } from "react-native";
 import Share from "react-native-share";
@@ -58,7 +59,7 @@ import { resolveForegroundLocationPermission } from "./ForegroundLocationPermiss
 import { advanceMiniappPingLiveness } from "./MiniappLiveness";
 import { listPhoneCalendarEvents, PhoneCalendarError } from "./PhoneCalendarService";
 import { LocalMiniappStorage } from "./LocalMiniappStorage";
-import acsMeetingService, { parseAcsOutgoingVideo, parseAcsVideoSource, resolveAcsAudioSource, } from "./AcsMeetingService";
+import acsMeetingService, { parseAcsCallOrigin, parseAcsOutgoingVideo, parseAcsVideoSource, resolveAcsAudioSource, } from "./AcsMeetingService";
 import { createSoftapCallDeps, SoftapCallError, SoftapCallTransport, SOFTAP_STEPS, } from "./SoftapCallTransport";
 import { awaitCleanupBarrier } from "./SoftapCleanupBarrier";
 import { softapTrace, softapTraceFailure } from "../utils/softapTrace";
@@ -253,6 +254,30 @@ function resetPermissionWarnings(packageName) {
 }
 /** How long a stalled SoftAP cleanup goes unremarked before it is logged. It is never abandoned. */
 const SOFTAP_CLEANUP_STALL_LOG_MS = 10_000;
+/**
+ * The WHIP listener's tombstone (3s) plus a margin for the close itself.
+ *
+ * Sized to the grace period rather than picked round, so an expiry here means something actually
+ * went wrong instead of meaning we guessed short.
+ */
+const SOFTAP_INGEST_CLOSE_WAIT_MS = 3_500;
+/** How long the glasses get to acknowledge their hotspot off, over BLE. */
+const SOFTAP_HOTSPOT_OFF_ACK_MS = 5_000;
+/** After a forced close there is nothing left to wait for, so this only catches a real failure. */
+const SOFTAP_FORCED_VERIFY_MS = 500;
+/** Reject with [reason] if [work] has not settled in [ms]. The work itself is not cancellable. */
+function withTimeout(work, ms, reason) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(reason)), ms);
+        work.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 /** How long the next call waits for the previous one's cleanup before telling the wearer about it. */
 const SOFTAP_CLEANUP_NARRATE_AFTER_MS = 250;
 // =============================================================================
@@ -269,6 +294,16 @@ class LocalMiniappRuntime {
      * before the first `await` and is what every later stage checks itself against.
      */
     softapAttempt = null;
+    /**
+     * The outer generation. Every async callback that can outlive an attempt checks itself against
+     * it and traces `softap_stale_callback` when it loses: ACS state, SoftAP progress, glasses
+     * stream status, scoped-network loss, and each checkpoint through the join.
+     *
+     * There are inner generations below this one — `AcsMeetingSession.joinGeneration` and
+     * `LocalWhipIngestSource.generation` — and they are not redundant. They fence work inside one
+     * native session against itself; this one fences whole attempts against each other, and only it
+     * knows that the wearer pressed Cancel before any of that native work existed.
+     */
     softapAttemptSeq = 0;
     /**
      * Why the previous SoftAP call's cleanup failed, if it did.
@@ -277,6 +312,13 @@ class LocalMiniappRuntime {
      * would not turn off is precisely what makes the next call fail somewhere far less legible.
      */
     softapCleanupError = null;
+    /**
+     * SoftAP teardown disables the glasses hotspot from the transport and again
+     * from the host barrier. Native used to throw `request_in_flight` on the
+     * second call, which was recorded as a cleanup failure and refused the next
+     * join. One queue so those overlapping disables wait their turn.
+     */
+    glassesHotspotCommand = Promise.resolve();
     /** Connected miniapps keyed by packageName. */
     connectedApps = new Map();
     /**
@@ -2886,6 +2928,26 @@ class LocalMiniappRuntime {
         });
         return false;
     }
+    /**
+     * OS-permission gate: checked, never requested.
+     *
+     * The prompt belongs at miniapp-open time, where it can be explained. Requesting here would put
+     * a system dialog on top of a join that has already started building a hotspot, and a wearer who
+     * denies it gets a call that half-exists. Missing means the join is refused with the permission
+     * named, so the miniapp can send them to Settings.
+     */
+    async requireOsPermission(packageName, requestId, feature, label) {
+        if (await permissions.check(feature))
+            return true;
+        softapTraceFailure("softap_permission_missing", { packageName, feature });
+        this.sendResult(packageName, requestId, false, undefined, {
+            code: MiniappErrorCode.PERMISSION_DENIED,
+            message: `This phone's ${label} permission is not granted. Grant it in Settings, then try again.`,
+            permission: feature,
+            operation: MiniappRequestType.MEETING_JOIN,
+        });
+        return false;
+    }
     async handlePhoto(packageName, payload, requestId) {
         // Manifest CAMERA permission gate.
         const app = this.connectedApps.get(packageName);
@@ -2905,7 +2967,7 @@ class LocalMiniappRuntime {
                 size: payload.size,
                 mode: payload.mode,
                 transferMethod: payload.transferMethod,
-                compress: payload.compress,
+                compress: parsePhotoCompression(payload.compress),
                 sound: payload.sound,
                 saveToGallery: payload.saveToGallery,
                 exposureTimeNs: payload.exposureTimeNs,
@@ -3136,12 +3198,24 @@ class LocalMiniappRuntime {
         // A meeting puts the glasses camera and mic in front of remote strangers; it
         // needs both declared, same as photo/stream and mic capture do individually.
         if (!this.requireManifestPermission(packageName, requestId, "CAMERA", "to join a meeting", MiniappRequestType.MEETING_JOIN) ||
-            !this.requireManifestPermission(packageName, requestId, "MICROPHONE", "to join a meeting", MiniappRequestType.MEETING_JOIN)) {
+            !this.requireManifestPermission(packageName, requestId, "MICROPHONE", "to join a meeting", MiniappRequestType.MEETING_JOIN) ||
+            !this.requireManifestPermission(packageName, requestId, "PHONE_CAMERA", "to join a meeting", MiniappRequestType.MEETING_JOIN)) {
             return;
         }
+        // Defensive only: these are prompted for when the wearer opens the miniapp, so by the time a
+        // join runs they are either granted or were refused minutes ago on a screen that explained
+        // them. Checked and never requested — a permission dialog on top of a half-built call is
+        // asked too late to explain itself, and ACS fails the join outright without the camera.
+        if (!(await this.requireOsPermission(packageName, requestId, PermissionFeatures.CAMERA, "camera")))
+            return;
+        if (!(await this.requireOsPermission(packageName, requestId, PermissionFeatures.MICROPHONE, "microphone")))
+            return;
         const meetingUrl = typeof payload.meetingUrl === "string" ? payload.meetingUrl : "";
         const token = typeof payload.token === "string" ? payload.token : "";
         const displayName = typeof payload.displayName === "string" ? payload.displayName : undefined;
+        // Diagnostic only. A miniapp that does not send it gets `unknown`, which is a third answer in
+        // the comparison rather than a default that would quietly file every old build under "created".
+        const origin = parseAcsCallOrigin(payload.origin);
         if (!meetingUrl || !token) {
             this.sendResult(packageName, requestId, false, undefined, {
                 code: MiniappErrorCode.INVALID_ARGUMENT,
@@ -3184,10 +3258,11 @@ class LocalMiniappRuntime {
                     transport: videoSource.type,
                     hasDisplayName: Boolean(displayName),
                     video: video ? `${video.width}x${video.height}@${video.fps}` : "default",
+                    origin,
                 });
                 const startedAt = Date.now();
                 try {
-                    const state = await this.joinSoftapMeeting(packageName, { meetingUrl, token, displayName, video });
+                    const state = await this.joinSoftapMeeting(packageName, { meetingUrl, token, displayName, video, origin });
                     softapTrace("meeting_join_result", {
                         packageName,
                         requestId: requestId ?? "none",
@@ -3215,14 +3290,21 @@ class LocalMiniappRuntime {
                 token,
                 videoSource,
                 displayName,
+                origin,
                 ...(video ? { video } : {}),
             });
             this.sendResult(packageName, requestId, true, state);
         }
         catch (err) {
+            // A SoftAP failure already knows what it was and where. Flattening every one of them to
+            // INTERNAL is what left the miniapp unable to tell "your Wi-Fi is off" — a condition with a
+            // two-tap fix — from an ACS timeout, so it showed the same shrug for both. The step comes
+            // along too: the same code at `hotspot` and at `scopedJoin` are different stories.
+            const softap = err instanceof SoftapCallError ? err : undefined;
             this.sendResult(packageName, requestId, false, undefined, {
-                code: MiniappErrorCode.INTERNAL,
+                code: softap?.code ?? MiniappErrorCode.INTERNAL,
                 message: err instanceof Error ? err.message : "ACS meeting join failed",
+                ...(softap ? { step: softap.step } : {}),
             });
         }
     }
@@ -3417,15 +3499,22 @@ class LocalMiniappRuntime {
             meetingUrl: args.meetingUrl,
             token: args.token,
             displayName: args.displayName,
+            video: args.video,
             awaitFirstFrame: () => acsMeetingService.waitForFirstFrame(SOFTAP_FIRST_FRAME_MS),
             subsystems: {
                 setHotspotState: async (enabled) => {
-                    const status = await BluetoothSdk.setHotspotState(enabled);
+                    const status = await this.setGlassesHotspotState(enabled);
                     if (status.state === "enabled") {
                         return { state: status.state, ssid: status.ssid, password: status.password, localIp: status.localIp };
                     }
                     return { state: status.state };
                 },
+                isWifiEnabled: async () => {
+                    // A host that cannot answer reports "on" so the preflight stands aside; the native
+                    // throw at scopedJoin is what covers those platforms.
+                    const enabled = await acsMeetingService.isWifiEnabled();
+                    return enabled ?? true;
+                },
                 joinScopedNetwork: (ssid, passphrase, gateway) => acsMeetingService.joinScopedNetwork(ssid, passphrase, gateway),
                 leaveScopedNetwork: () => acsMeetingService.leaveScopedNetwork(),
                 cancelScopedNetworkJoin: () => acsMeetingService.cancelScopedNetworkJoin(),
@@ -3437,6 +3526,18 @@ class LocalMiniappRuntime {
                 awaitValidatedDefaultNetwork: () => acsMeetingService.awaitValidatedDefaultNetwork(),
                 onGlassesStreamStatus: (listener) => {
                     const sub = BluetoothSdk.addListener("stream_status", (event) => {
+                        // The glasses narrate over BLE, which is slow enough that a status from the previous
+                        // publish can land after this attempt was retired — and it is narration, so it would
+                        // be written straight onto the new call's checklist as if it were happening now.
+                        if (this.softapAttempt !== attempt || attempt.cancelled) {
+                            softapTrace("softap_stale_callback", {
+                                source: "glasses_stream_status",
+                                attempt: attempt.id,
+                                status: event.status,
+                                current: this.softapAttempt?.id ?? "none",
+                            });
+                            return;
+                        }
                         listener({
                             status: event.status,
                             streamId: event.streamId,
@@ -3451,6 +3552,7 @@ class LocalMiniappRuntime {
                     token: options.token,
                     videoSource: options.videoSource,
                     displayName: options.displayName,
+                    origin: args.origin,
                     ...(args.video ? { video: args.video } : {}),
                 }),
                 leaveMeeting: (pkg) => acsMeetingService.leave(pkg),
@@ -3678,8 +3780,10 @@ class LocalMiniappRuntime {
         // Start Call's `teams:create` return `Request failed (503)` — Cloudflare, no internet, not a
         // Teams configuration problem.
         const defaultNetworkStartedAt = Date.now();
+        let defaultNetworkOk = false;
         try {
             const network = await acsMeetingService.awaitDefaultNetworkAfterHotspot();
+            defaultNetworkOk = true;
             softapTrace("softap_teardown_step", {
                 attempt: attempt.id,
                 step: "awaitValidatedDefaultNetwork",
@@ -3704,9 +3808,12 @@ class LocalMiniappRuntime {
                 reason: error instanceof Error ? error.message : String(error),
             });
         }
+        const defaultNetworkMs = Date.now() - defaultNetworkStartedAt;
         const acsLeaveStartedAt = Date.now();
+        let acsLeaveOk = false;
         try {
             const outcome = await acsMeetingService.leaveAndAwait(attempt.packageName);
+            acsLeaveOk = outcome.completed;
             softapTrace("softap_teardown_step", {
                 attempt: attempt.id,
                 step: "acsLeaveAndAwait",
@@ -3741,6 +3848,10 @@ class LocalMiniappRuntime {
             step: "scopedLostListener",
             outcome: hadScopedLostListener ? "ok" : "not taken",
         });
+        failures.push(...(await this.settleSoftapTeardown(attempt, {
+            acsLeave: { ok: acsLeaveOk, durationMs: Date.now() - acsLeaveStartedAt },
+            defaultNetwork: { ok: defaultNetworkOk, durationMs: defaultNetworkMs },
+        })));
         if (failures.length > 0) {
             this.softapCleanupError = failures.join("; ");
             console.warn("[LocalMiniappRuntime] softap_cleanup_failed", { attempt: attempt.id, failures });
@@ -3759,6 +3870,117 @@ class LocalMiniappRuntime {
         if (endFailure)
             throw endFailure;
     }
+    setGlassesHotspotState(enabled) {
+        const run = this.glassesHotspotCommand.then(() => BluetoothSdk.setHotspotState(enabled), () => BluetoothSdk.setHotspotState(enabled));
+        this.glassesHotspotCommand = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * The last two gates, and the point where a timeout stops being treated as consent.
+     *
+     * Four things have to be true before the next call may start: this device is out of the ACS
+     * call, the WHIP listener's port is released, the glasses have acknowledged their hotspot off,
+     * and the phone has a validated default route again. The first and last already ran; this adds
+     * the two that were never waited for at all, and the ones that produced the stop-then-start
+     * failure — the listener was still inside its 3s tombstone and the glasses AP was still up.
+     *
+     * A bound that expires is not success. It means the resource is still held by a call nobody is
+     * in any more, so it is taken by force and re-verified. Only if *that* fails does the next join
+     * get refused, which is a worse outcome than a slow teardown and a better one than two calls
+     * sharing a port.
+     *
+     * @returns failures to record; a non-empty list refuses the next join.
+     */
+    async settleSoftapTeardown(attempt, earlier) {
+        const ingestStartedAt = Date.now();
+        let ingestClosed = false;
+        try {
+            ingestClosed = await acsMeetingService.awaitIngestClosed(SOFTAP_INGEST_CLOSE_WAIT_MS);
+        }
+        catch (error) {
+            softapTraceFailure("softap_teardown_step", {
+                attempt: attempt.id,
+                step: "awaitIngestClosed",
+                outcome: "failed",
+                reason: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const ingestMs = Date.now() - ingestStartedAt;
+        const hotspotStartedAt = Date.now();
+        let hotspotOff = false;
+        let hotspotReason = "";
+        try {
+            // Idempotent by design — the command asks for "disabled" rather than toggling — so sending
+            // it again after the transport's own stop costs nothing and is the only way to get an ack
+            // that is bound to a deadline we chose.
+            const status = await withTimeout(this.setGlassesHotspotState(false), SOFTAP_HOTSPOT_OFF_ACK_MS, "hotspot_off_ack_timeout");
+            hotspotOff = status.state === "disabled";
+            hotspotReason = status.state;
+        }
+        catch (error) {
+            hotspotReason = error instanceof Error ? error.message : String(error);
+        }
+        const hotspotMs = Date.now() - hotspotStartedAt;
+        softapTrace("softap_teardown_settled", {
+            attempt: attempt.id,
+            acsLeaveMs: earlier.acsLeave.durationMs,
+            acsLeaveOk: earlier.acsLeave.ok,
+            ingestClosedMs: ingestMs,
+            ingestClosed,
+            hotspotOffMs: hotspotMs,
+            hotspotOff,
+            hotspotDetail: hotspotReason,
+            defaultNetworkMs: earlier.defaultNetwork.durationMs,
+            defaultNetworkOk: earlier.defaultNetwork.ok,
+        });
+        if (ingestClosed && hotspotOff)
+            return [];
+        return this.forceSoftapCleanup(attempt, { ingestClosed, hotspotOff, hotspotReason });
+    }
+    /**
+     * Take back what the bounded waits could not confirm was released.
+     *
+     * Runs only after a gate timed out, and re-verifies rather than assuming: the whole reason the
+     * barrier exists is that "it has probably finished by now" is what broke restarts.
+     */
+    async forceSoftapCleanup(attempt, gates) {
+        const failures = [];
+        softapTraceFailure("softap_teardown_forced", {
+            attempt: attempt.id,
+            ingestClosed: gates.ingestClosed,
+            hotspotOff: gates.hotspotOff,
+            hotspotDetail: gates.hotspotReason,
+        });
+        if (!gates.ingestClosed) {
+            try {
+                await acsMeetingService.forceCloseIngest();
+                // Re-asked, not assumed: `forceCloseIngest` skips the tombstone, so the latch should be
+                // open immediately. A short bound here is enough and a failure is real.
+                const closed = await acsMeetingService.awaitIngestClosed(SOFTAP_FORCED_VERIFY_MS);
+                if (!closed)
+                    failures.push("the video receiver did not release its port");
+            }
+            catch (error) {
+                failures.push(`forced ingest close: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (!gates.hotspotOff) {
+            try {
+                const status = await withTimeout(this.setGlassesHotspotState(false), SOFTAP_HOTSPOT_OFF_ACK_MS, "hotspot_off_ack_timeout");
+                if (status.state !== "disabled")
+                    failures.push(`the glasses hotspot is still ${status.state}`);
+            }
+            catch (error) {
+                failures.push(`glasses hotspot off: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        softapTrace("softap_teardown_forced_done", {
+            attempt: attempt.id,
+            recovered: failures.length === 0,
+            failures: failures.join("; "),
+        });
+        return failures;
+    }
     async handleMeetingLeave(packageName, requestId) {
         const startedAt = Date.now();
         softapTrace("meeting_leave_request", {