@mentra/engine 0.1.0-beta.0

package/src/services/cloudStreamApi.ts

@@ -0,0 +1,154 @@
+/**
+ * Managed-stream provisioning over the cloud-v2 runtime (cloud-client REST):
+ *
+ *   POST   /api/camera/stream      -> provision (Cloudflare live input)
+ *   GET    /api/camera/stream/:id  -> provider's ingest status
+ *   DELETE /api/camera/stream/:id  -> teardown
+ *
+ * Drop-in replacement for the legacy `v2StreamApi` (which hit the v1 cloud's
+ * /api/v2/client/streams/managed on backend_url): same exported shapes, so
+ * PhoneStreamCoordinator is unchanged apart from the import. Local miniapps
+ * use ONLY this path — no legacy V1 transport.
+ *
+ * Errors are tagged with stage "provision"/"status"/"teardown" and transport
+ * "cloud-rest" so a miniapp sees exactly where and on which leg it broke.
+ */
+
+import {cloudClientService as cloudClient} from "./CloudClientService"
+
+/**
+ * Restream destination. The full stream key is part of the URL — Cloudflare
+ * appends nothing on the publish side. `name` is a human label that surfaces
+ * in Cloudflare's dashboard but doesn't affect routing.
+ */
+export interface RestreamDestination {
+  url: string
+  name?: string
+}
+
+/** Caller-facing shape: either a bare URL string or the full object. */
+export type RestreamDestinationInput = string | RestreamDestination
+
+export interface ProvisionResult {
+  liveInputId: string
+  rtmpUrl: string
+  srtUrl?: string
+  hlsUrl: string
+  dashUrl: string
+  webrtcUrl?: string
+  webrtcPublishUrl?: string
+}
+
+export interface CloudflareStatus {
+  isConnected: boolean
+  state?: string | null
+  connectedAt?: string
+  lastSeenAt?: string
+  reason?: string
+}
+
+export type StreamApiStage = "provision" | "status" | "teardown"
+
+export class StreamApiError extends Error {
+  readonly transport = "cloud-rest" as const
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly stage: StreamApiStage,
+  ) {
+    super(message)
+    this.name = "StreamApiError"
+  }
+}
+
+/** The cloud-v2 runtime's ManagedStream wire shape (open records, see protocol). */
+interface ManagedStreamWire {
+  streamId: string
+  ingest: {
+    url?: string
+    streamKey?: string
+    rtmpUrl?: string
+    srtUrl?: string
+    webrtcPublishUrl?: string
+  }
+  playback: {
+    hls?: string
+    dash?: string
+    webrtc?: string
+  }
+}
+
+/**
+ * Provision a managed stream on the cloud-v2 runtime. Returns ready-to-publish
+ * ingest URLs (credentials embedded) plus the playback URLs.
+ */
+export async function provisionManagedStream(
+  restreamDestinations?: RestreamDestinationInput[],
+): Promise<ProvisionResult> {
+  let wire: ManagedStreamWire
+  try {
+    wire = (await cloudClient.startManagedStream(
+      restreamDestinations && restreamDestinations.length > 0 ? {restreamDestinations} : {},
+    )) as ManagedStreamWire
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_PROVISION_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "provision",
+    )
+  }
+
+  const ingest = wire.ingest ?? {}
+  const playback = wire.playback ?? {}
+  const rtmpUrl = ingest.rtmpUrl ?? (ingest.url && ingest.streamKey ? `${ingest.url}${ingest.streamKey}` : "")
+  if (!playback.hls || !playback.dash) {
+    throw new StreamApiError(
+      "STREAM_PROVISION_INCOMPLETE",
+      `runtime returned no playback URLs for stream ${wire.streamId}`,
+      "provision",
+    )
+  }
+
+  return {
+    liveInputId: wire.streamId,
+    rtmpUrl,
+    srtUrl: ingest.srtUrl,
+    hlsUrl: playback.hls,
+    dashUrl: playback.dash,
+    webrtcUrl: playback.webrtc,
+    webrtcPublishUrl: ingest.webrtcPublishUrl,
+  }
+}
+
+/** The provider's view of the ingest: is the device's push arriving? */
+export async function getManagedStreamStatus(liveInputId: string): Promise<CloudflareStatus> {
+  try {
+    const s = await cloudClient.getManagedStreamStatus(liveInputId)
+    return {
+      isConnected: s.isConnected,
+      state: s.state,
+      connectedAt: s.connectedAt,
+      lastSeenAt: s.lastSeenAt,
+      reason: s.reason,
+    }
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_STATUS_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "status",
+    )
+  }
+}
+
+/** Tear down the provider stream. */
+export async function teardownManagedStream(liveInputId: string): Promise<void> {
+  try {
+    await cloudClient.stopManagedStream(liveInputId)
+  } catch (err) {
+    throw new StreamApiError(
+      "STREAM_TEARDOWN_FAILED",
+      err instanceof Error ? err.message : String(err),
+      "teardown",
+    )
+  }
+}

package/src/services/gallerySyncClock.ts

@@ -0,0 +1,39 @@
+/**
+ * Clock skew detection for gallery sync (phone vs glasses).
+ * Phone pushes time to glasses only when skew is detected during sync.
+ */
+
+export const CLOCK_SKEW_TOLERANCE_MS = 60_000
+
+export type ClockSkewReason = "watermark_ahead_of_glasses" | "wall_clock_drift" | ""
+
+export interface ClockSkewResult {
+  skewed: boolean
+  reason: ClockSkewReason
+}
+
+export function detectClockSkew(
+  phoneNow: number,
+  glassesServerTime: number,
+  lastSyncTime: number,
+  toleranceMs: number = CLOCK_SKEW_TOLERANCE_MS,
+): ClockSkewResult {
+  if (lastSyncTime > glassesServerTime + toleranceMs) {
+    return {skewed: true, reason: "watermark_ahead_of_glasses"}
+  }
+  if (Math.abs(phoneNow - glassesServerTime) > toleranceMs) {
+    return {skewed: true, reason: "wall_clock_drift"}
+  }
+  return {skewed: false, reason: ""}
+}
+
+export function isSyncManifestEmpty(syncData: {
+  api_version?: number
+  captures?: unknown[]
+  changed_files?: unknown[]
+}): boolean {
+  if ((syncData.api_version || 0) >= 2 && syncData.captures && syncData.captures.length > 0) {
+    return false
+  }
+  return !syncData.changed_files || syncData.changed_files.length === 0
+}

package/src/services/glassesClockSync.ts

@@ -0,0 +1,115 @@
+/**
+ * Push phone time to glasses only when clock skew is detected (gallery sync, OTA, etc.).
+ */
+
+import BluetoothSdk from "@mentra/bluetooth-sdk/internal"
+import {BgTimer} from "../utils/timers"
+import {useGlassesStore} from "../stores/glasses"
+
+import {getAsgOtaVersionUrl} from "./asgOtaVersionUrl"
+import {detectClockSkew} from "./gallerySyncClock"
+
+export const CLOCK_SETTLE_MS = 500
+
+const OTA_CLOCK_FIX_COOLDOWN_MS = 30_000
+let lastOtaClockFixAt = 0
+// Coalesce concurrent OTA clock-fix attempts. Glasses can emit two clock_skew events
+// back-to-back during BLE handshake; without this guard both would await the BLE fix
+// + retry pair before either updated `lastOtaClockFixAt`.
+let inflightOtaClockFix: Promise<boolean> | null = null
+
+/** @internal test-only */
+export function resetOtaClockFixCooldownForTests(): void {
+  lastOtaClockFixAt = 0
+  inflightOtaClockFix = null
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => BgTimer.setTimeout(resolve, ms))
+}
+
+/**
+ * Set glasses system clock from phone when skew is detected.
+ */
+export async function fixGlassesClockIfSkewed(glassesServerTime: number, lastSyncTime = 0): Promise<boolean> {
+  const {skewed, reason} = detectClockSkew(Date.now(), glassesServerTime, lastSyncTime)
+  if (!skewed) {
+    return false
+  }
+  console.log(`[GlassesClockSync] ⏰ Clock skew detected (${reason}) — setting glasses time from phone`)
+  await BluetoothSdk.setSystemTime(Date.now())
+  await delay(CLOCK_SETTLE_MS)
+  return true
+}
+
+/**
+ * After glasses report OTA failure due to clock skew, fix time and restart
+ * through the normal phone-driven ota_start path.
+ */
+export async function handleOtaClockSkewFromGlasses(
+  errorCode: string | undefined,
+  glassesTimeMs?: number,
+): Promise<boolean> {
+  if (Date.now() - lastOtaClockFixAt < OTA_CLOCK_FIX_COOLDOWN_MS) {
+    return false
+  }
+
+  const hasGlassesTime = typeof glassesTimeMs === "number" && Number.isFinite(glassesTimeMs) && glassesTimeMs > 0
+
+  if (errorCode === "ssl_error") {
+    if (!hasGlassesTime) {
+      return false
+    }
+    const {skewed} = detectClockSkew(Date.now(), glassesTimeMs, 0)
+    if (!skewed) {
+      return false
+    }
+    console.log("[GlassesClockSync] ⏰ OTA ssl_error with wall-clock drift — treating as clock skew")
+  } else if (errorCode !== "clock_skew") {
+    return false
+  }
+
+  // Coalesce concurrent attempts: if a fix is already in flight, await its result instead
+  // of racing it through the cooldown guard.
+  if (inflightOtaClockFix) {
+    return inflightOtaClockFix
+  }
+
+  const glassesTime = hasGlassesTime ? glassesTimeMs : Date.now() - 86_400_000
+
+  inflightOtaClockFix = (async () => {
+    try {
+      const fixed = await fixGlassesClockIfSkewed(glassesTime, 0)
+      if (!fixed) {
+        return false
+      }
+
+      lastOtaClockFixAt = Date.now()
+      const {buildNumber, otaVersionUrl} = useGlassesStore.getState()
+      const manifestUrl = getAsgOtaVersionUrl(otaVersionUrl, buildNumber)
+      console.log("[GlassesClockSync] ⏰ Restarting OTA with ota_start after clock fix")
+      await BluetoothSdk.startOtaUpdate(manifestUrl)
+      return true
+    } finally {
+      inflightOtaClockFix = null
+    }
+  })()
+
+  return inflightOtaClockFix
+}
+
+/**
+ * Proactive fix when version_info includes glasses system_time_ms before OTA manifest checks.
+ */
+export async function maybeFixGlassesClockFromVersionInfo(systemTimeMs: number | undefined): Promise<boolean> {
+  if (typeof systemTimeMs !== "number" || systemTimeMs <= 0) {
+    return false
+  }
+
+  const fixed = await fixGlassesClockIfSkewed(systemTimeMs, 0)
+  if (!fixed) {
+    return false
+  }
+
+  return true
+}

package/src/services/manifestVersionGate.ts

@@ -0,0 +1,43 @@
+import semver from "semver"
+
+/**
+ * Pure helper extracted from `AppRegistry.checkManifestVersions` so it
+ * can be unit-tested without dragging in the `expo-file-system`
+ * transitively-React-Native dependency tree.
+ *
+ * Returns `{ok: true}` when the manifest is compatible with the host,
+ * or `{ok: false, reason}` with a user-facing string. Manifests missing
+ * either field pass through (legacy single-bundle bundles).
+ *
+ * `sdkVersion` is the SDK ABI the bundle targets; `minHostVersion` is
+ * the host floor the miniapp requires. Both must satisfy semver-coerce.
+ * Strings that don't coerce are treated as "unspecified" — the
+ * CLI's validateManifest catches malformed inputs at install time so
+ * this helper stays permissive at the policy layer.
+ */
+export function checkManifestVersions(
+  manifest: {sdkVersion?: string; minHostVersion?: string} | null,
+  options: {hostVersion: string; supportedSdkRange: string},
+): {ok: true} | {ok: false; reason: string} {
+  if (!manifest) return {ok: true}
+  if (manifest.minHostVersion) {
+    const cleanHost = semver.valid(semver.coerce(options.hostVersion) ?? options.hostVersion)
+    const cleanMin = semver.valid(semver.coerce(manifest.minHostVersion) ?? manifest.minHostVersion)
+    if (cleanHost && cleanMin && semver.lt(cleanHost, cleanMin)) {
+      return {
+        ok: false,
+        reason: `Requires MentraOS ${manifest.minHostVersion}+; this host is ${options.hostVersion}.`,
+      }
+    }
+  }
+  if (manifest.sdkVersion) {
+    const cleanSdk = semver.valid(semver.coerce(manifest.sdkVersion) ?? manifest.sdkVersion)
+    if (cleanSdk && !semver.satisfies(cleanSdk, options.supportedSdkRange)) {
+      return {
+        ok: false,
+        reason: `Built for SDK ${manifest.sdkVersion}; host supports ${options.supportedSdkRange}.`,
+      }
+    }
+  }
+  return {ok: true}
+}