@glassly/engine 0.1.0-dev.0

package/src/services/CloudClientService.ts

@@ -0,0 +1,1031 @@
+/**
+ * Owns the singleton `@glassly/cloud-client` (CloudClient) for the engine runtime
+ * — the keystone move that pulls backend comms INTO engine.
+ *
+ * engine constructs the client from engine-owned pieces (the native UDP socket,
+ * the MMKV secure store, the cloud-status store) plus the two things the host
+ * provides through the engine front door: `auth.getSubjectToken` (the one
+ * permanent seam — the OEM owns login) and the resolved cloud endpoints
+ * (`config.coreUrl/runtimeUrl`, computed host-side from dev/settings). On init it
+ * exposes cloud runtime methods directly from this service, so the host no longer
+ * injects a cloud adapter — engine owns construction and wiring.
+ *
+ * The local-miniapp path drives the cloud's transcription/translation through
+ * this service.
+ */
+import {CloudClient, setNativeHttp, setNativeUdp, setSecureStorage} from "@glassly/cloud-client/react-native"
+import type {PreinstalledMiniappRegistry, RuntimeSnapshot} from "@glassly/cloud-client/react-native"
+import type {SubjectTokenType} from "@glassly/cloud-client"
+import {Platform} from "react-native"
+import type {AudioSubscription, QuotaStatusPayload, TranscriptionData, TranslationData} from "@glassly/cloud-protocol"
+
+import BluetoothSdk from "@glassly/bluetooth-sdk/internal"
+import CrustModule from "@glassly/crust"
+import {getAuth, getConfigValues} from "../runtime/bootstrap"
+import {useSettingsStore, SETTINGS} from "../stores/settings"
+import {type CloudClientStatusSnapshot, type MiniappAuthToken} from "../runtime/config"
+import {createCloudUdpSocket} from "../utils/cloudClient/RnUdpAdapter"
+import {cloudSecureStore} from "../utils/cloudClient/cloudSecureStore"
+import {storage as mmkvStorage} from "../utils/storage"
+import {useCloudClientStatusStore} from "../stores/cloudClientStatus"
+import {islandNotifications} from "./NotificationsEmitter"
+import {BgTimer} from "../utils/timers"
+import {logCloudV2TranscriptMetric} from "./CloudTranscriptE2EMetrics"
+import {isLocalUserId, LocalMiniappUserIdentity} from "./LocalMiniappUserIdentity"
+import {migrateLocalMiniappData, type LocalMiniappDataMigrationBackend} from "./LocalMiniappDataMigration"
+import {nativeHttpResponseBody} from "./NativeHttpResponse"
+
+const LOG_TAG = "cloudClient"
+type CloudCore = NonNullable<CloudClient["core"]>
+
+// Persistent cloud-disconnect detector: the cloud-client reconnect loop is infinite
+// and never surfaces a "giving up" signal, so "persistent failure" = the session has
+// been continuously NOT connected for this long. A quick reconnect cancels it; brief
+// flaps that recover don't fire. Raised as engine.notifications(connection_failed_persistent).
+const CLOUD_PERSISTENT_FAILURE_MS = 60_000
+const LOCAL_MINIAPP_USER_ID_KEY = "glassly.localMiniapp.userId"
+
+/** Cancel the pending persistent-failure alarm + re-arm for the next outage. */
+function clearPersistentFailureAlarm(): void {
+  if (persistentFailureTimer) {
+    BgTimer.clearTimeout(persistentFailureTimer)
+    persistentFailureTimer = null
+  }
+  persistentFailureNotified = false
+}
+
+type Lc3FrameSizeBytes = 20 | 40 | 60
+
+// Neutral last-ditch fallbacks (reachable under `adb reverse`) for when the host
+// passes no endpoints. The host normally resolves the real URLs (dev override /
+// Metro host / env) and hands them in via `engine.configure({config})`.
+const FALLBACK_CORE_URL = "http://localhost:3000"
+const FALLBACK_RUNTIME_URL = "http://localhost:3001"
+const LOCAL_AUTH_PORT = 3002
+
+let client: CloudClient | null = null
+let connected = false
+let persistentFailureTimer: ReturnType<typeof BgTimer.setTimeout> | null = null
+let persistentFailureNotified = false
+let audioSubscriptions: AudioSubscription[] = []
+let transportsReady = false
+/** Endpoints to build with — seeded from config, overridable via reconnect(). */
+let endpointsOverride: {core: string; runtime: string} | null = null
+let runtimeStatusUnsubscribe: (() => void) | null = null
+let transcriptUnsubscribe: (() => void) | null = null
+let translationUnsubscribe: (() => void) | null = null
+let quotaUnsubscribe: (() => void) | null = null
+let authStateUnsubscribe: (() => void) | null = null
+let localDevRuntimeToken: {runtimeUrl: string; token: string; expiresAtMs: number} | null = null
+let lc3FrameSizeUnsubscribe: (() => void) | null = null
+let disableCloudUnsubscribe: (() => void) | null = null
+let coreTokenSyncPromise: Promise<string> | null = null
+/**
+ * A device-local namespace (`local_…`) whose data still needs to be adopted
+ * into the account namespace. Set when a sign-in displaces a local id; cleared
+ * once {@link adoptLocalNamespace} has moved the data.
+ */
+let pendingLocalNamespace: string | null = null
+
+/**
+ * Moves blob bytes between user directories during namespace adoption.
+ * Registered by LocalMiniappRuntime (which owns the BlobStore instance) so this
+ * service doesn't import it and create a cycle. Absent in tests / before the
+ * runtime boots, in which case only the key-value stores migrate.
+ */
+type BlobNamespaceMigrator = (fromUserId: string, toUserId: string) => {moved: number; skipped: number}
+let blobNamespaceMigrator: BlobNamespaceMigrator | null = null
+
+/**
+ * Register the blob-bytes half of namespace adoption. Called by
+ * LocalMiniappRuntime at construction — it owns the BlobStore instance, and
+ * having it push the hook here keeps this service from importing the runtime.
+ */
+export function setBlobNamespaceMigrator(migrator: BlobNamespaceMigrator | null): void {
+  blobNamespaceMigrator = migrator
+}
+
+/** Result-free view of MMKV, as the migration's plain get/set/remove/keys. */
+const migrationBackend: LocalMiniappDataMigrationBackend = {
+  get(key: string): unknown | null {
+    const result = mmkvStorage.load<unknown>(key)
+    return result.is_ok() ? result.value : null
+  },
+  set(key: string, value: unknown): void {
+    const result = mmkvStorage.save(key, value)
+    if (result.is_error()) throw result.error
+  },
+  remove(key: string): void {
+    const result = mmkvStorage.remove(key)
+    if (result.is_error()) throw result.error
+  },
+  keys(): string[] {
+    return mmkvStorage.getAllKeys()
+  },
+}
+
+/**
+ * Adopt data written under a device-local namespace into the signed-in
+ * account's, so miniapp state created while cloud was disabled survives
+ * sign-in. No-op unless a sign-in actually displaced a local id.
+ */
+function adoptLocalNamespace(coreUserId: string): void {
+  const from = pendingLocalNamespace
+  if (!from) return
+  // Clear first: a failure must not re-run on every subsequent resolve, and the
+  // migration is idempotent anyway.
+  pendingLocalNamespace = null
+  if (!coreUserId || from === coreUserId) return
+
+  try {
+    const keys = migrateLocalMiniappData(migrationBackend, from, coreUserId)
+    const blobs = blobNamespaceMigrator?.(from, coreUserId) ?? {moved: 0, skipped: 0}
+    if (keys.moved || keys.skipped || blobs.moved || blobs.skipped) {
+      console.log(
+        `${LOG_TAG}: adopted local miniapp data into account namespace ` +
+          `(keys ${keys.moved} moved/${keys.skipped} skipped, blobs ${blobs.moved} moved/${blobs.skipped} skipped)`,
+      )
+    }
+  } catch (err) {
+    console.warn(`${LOG_TAG}: local namespace adoption failed: ${(err as Error)?.message ?? err}`)
+  }
+}
+
+const localMiniappUserIdentity = new LocalMiniappUserIdentity({
+  get(): string | null {
+    const result = mmkvStorage.load<string>(LOCAL_MINIAPP_USER_ID_KEY)
+    return result.is_ok() ? result.value : null
+  },
+  set(userId: string): void {
+    const result = mmkvStorage.save(LOCAL_MINIAPP_USER_ID_KEY, userId)
+    if (result.is_error()) throw result.error
+  },
+  remove(): void {
+    const result = mmkvStorage.remove(LOCAL_MINIAPP_USER_ID_KEY)
+    if (result.is_error()) throw result.error
+  },
+})
+
+const transcriptListeners = new Set<(d: TranscriptionData) => void>()
+const translationListeners = new Set<(d: TranslationData) => void>()
+const quotaListeners = new Set<(d: QuotaStatusPayload) => void>()
+const statusListeners = new Set<(snapshot: CloudClientStatusSnapshot) => void>()
+const connectionListeners = new Set<(connected: boolean) => void>()
+
+function resolveEndpoints(): {core: string; runtime: string} {
+  if (endpointsOverride) return endpointsOverride
+  const cfg = getConfigValues()
+  return {
+    core: cfg.coreUrl?.trim() || FALLBACK_CORE_URL,
+    runtime: cfg.runtimeUrl?.trim() || FALLBACK_RUNTIME_URL,
+  }
+}
+
+function getCoreClient(): CloudCore {
+  if (!client) construct()
+  const core = client?.core
+  if (!core) throw new Error("cloud client core not configured")
+  return core
+}
+
+function syncCoreAccessTokenToBluetooth(): Promise<string> {
+  if (coreTokenSyncPromise) return coreTokenSyncPromise
+
+  coreTokenSyncPromise = syncCoreAccessTokenToBluetoothInternal().finally(() => {
+    coreTokenSyncPromise = null
+  })
+  return coreTokenSyncPromise
+}
+
+async function syncCoreAccessTokenToBluetoothInternal(): Promise<string> {
+  if (!client) construct()
+  const c = client
+  if (!c) throw new Error("cloud client not initialized")
+
+  const token = await c.auth.getCoreToken()
+  if (c !== client) {
+    throw new Error("cloud client changed while syncing core token")
+  }
+  adoptLocalNamespace(c.auth.identity.glasslyUserId)
+  localMiniappUserIdentity.remember(c.auth.identity.glasslyUserId)
+  const result = await useSettingsStore.getState().setSetting(SETTINGS.core_token.key, token, false)
+  if (result.is_error()) {
+    throw result.error
+  }
+
+  try {
+    await BluetoothSdk.updateBluetoothSettings({[SETTINGS.core_token.key]: token})
+  } catch (err) {
+    console.warn(`${LOG_TAG}: direct Bluetooth core_token sync failed: ${(err as Error)?.message ?? err}`)
+  }
+
+  return token
+}
+
+function frameSizeBytes(): Lc3FrameSizeBytes {
+  // Read LIVE from the engine settings store (the source of truth) so a
+  // reconnect after a glasses swap (G1=20 ↔ G2=40) picks up the new frame size,
+  // not the one-time engine.configure({config}) snapshot. Falls back to the
+  // config value (set at boot) then 20 when the setting is unset.
+  const fromSettings = useSettingsStore.getState().getSetting(SETTINGS.lc3_frame_size.key)
+  const size = fromSettings ?? getConfigValues().audioFrameSizeBytes
+  return size === 20 || size === 40 || size === 60 ? size : 20
+}
+
+async function getSubjectToken(): Promise<{token: string; type: SubjectTokenType}> {
+  const a = getAuth()
+  if (!a) throw new Error("cloudClient: engine.configure({auth}) not called")
+  const r = await a.getSubjectToken()
+  // IslandAuth's SubjectTokenType is intentionally open (`string & {}`) so OEMs
+  // can use other token kinds; cloud-client's is a closed union. The host's
+  // actual value ("supabase") is valid — narrow at this boundary.
+  return {token: r.token, type: r.type as SubjectTokenType}
+}
+
+function normalizeExpiresAt(expiresAt: number): number {
+  return expiresAt < 10_000_000_000 ? expiresAt * 1000 : expiresAt
+}
+
+function shouldUseLocalDevRuntimeToken(endpoints: {runtime: string}): boolean {
+  if (!__DEV__) return false
+  try {
+    const host = new URL(endpoints.runtime).hostname
+    return host === "localhost" || host === "127.0.0.1" || host === "10.0.2.2"
+  } catch {
+    return false
+  }
+}
+
+async function getLocalDevRuntimeToken(runtimeEndpoint: string, opts?: {forceRefresh?: boolean}): Promise<string> {
+  const now = Date.now()
+  if (
+    !opts?.forceRefresh &&
+    localDevRuntimeToken?.runtimeUrl === runtimeEndpoint &&
+    localDevRuntimeToken.expiresAtMs - now > 60_000
+  ) {
+    return localDevRuntimeToken.token
+  }
+
+  const base = new URL(runtimeEndpoint)
+  base.port = String(LOCAL_AUTH_PORT)
+  base.pathname = "/api/dev/runtime-token"
+  base.search = new URLSearchParams({userId: "local-phone-user", tenantId: "glassly"}).toString()
+
+  const res = await fetch(base.toString())
+  if (!res.ok) {
+    throw new Error(`cloudClient: local dev runtime token failed (${res.status})`)
+  }
+  const body = (await res.json()) as {access_token?: string; expires_in?: number}
+  if (!body.access_token) {
+    throw new Error("cloudClient: local dev runtime token response missing access_token")
+  }
+  localDevRuntimeToken = {
+    runtimeUrl: runtimeEndpoint,
+    token: body.access_token,
+    expiresAtMs: now + (body.expires_in ?? 300) * 1000,
+  }
+  return body.access_token
+}
+
+function toCloudClientStatusSnapshot(snapshot: RuntimeSnapshot): CloudClientStatusSnapshot {
+  return {status: snapshot.status, audioTransport: snapshot.audioTransport}
+}
+
+function currentRuntimeStatus(): CloudClientStatusSnapshot {
+  const state = useCloudClientStatusStore.getState()
+  return {status: state.status, audioTransport: state.audioTransport}
+}
+
+function setRuntimeStatus(snapshot: RuntimeSnapshot): void {
+  useCloudClientStatusStore.getState().setSnapshot(snapshot)
+  emitStatus(toCloudClientStatusSnapshot(snapshot))
+}
+
+function resetRuntimeStatus(): void {
+  useCloudClientStatusStore.getState().reset()
+  emitStatus(currentRuntimeStatus())
+}
+
+function stringifyMeta(meta: unknown): string {
+  if (!meta || typeof meta !== "object") return ""
+  try {
+    return ` ${JSON.stringify(meta)}`
+  } catch {
+    return ""
+  }
+}
+
+const cloudLogger = {
+  debug: (msg: string, meta?: unknown) => console.log(`${LOG_TAG}: debug: ${msg}${stringifyMeta(meta)}`),
+  info: (msg: string, meta?: unknown) => console.log(`${LOG_TAG}: info: ${msg}${stringifyMeta(meta)}`),
+  warn: (msg: string, meta?: unknown) => console.warn(`${LOG_TAG}: warn: ${msg}${stringifyMeta(meta)}`),
+  error: (msg: string, meta?: unknown) => console.warn(`${LOG_TAG}: error: ${msg}${stringifyMeta(meta)}`),
+}
+
+function notifyConnectionListeners(next: boolean): void {
+  for (const l of connectionListeners) {
+    try {
+      l(next)
+    } catch (err) {
+      console.warn(`${LOG_TAG}: connection listener threw: ${(err as Error)?.message ?? err}`)
+    }
+  }
+}
+
+function extractUnsubscribe(sub: unknown): (() => void) | null {
+  const candidates: unknown[] = []
+  const s = sub as Record<string, unknown> | null | undefined
+  if (s && typeof s === "object") {
+    candidates.push(s)
+    candidates.push((s.value as Record<string, unknown>)?.subscription)
+    candidates.push((s.data as Record<string, unknown>)?.subscription)
+    candidates.push(s.subscription)
+  }
+  for (const c of candidates) {
+    const unsub = (c as {unsubscribe?: unknown})?.unsubscribe
+    if (typeof unsub === "function") return unsub as () => void
+  }
+  return null
+}
+
+function ensureAuthWatch(): void {
+  if (authStateUnsubscribe) return
+  authStateUnsubscribe = () => {}
+
+  const auth = getAuth()
+  if (!auth?.onStateChange) return
+
+  let reconnectPending = false
+  try {
+    const sub = auth.onStateChange((event, session) => {
+      if (event === "SIGNED_OUT") {
+        localMiniappUserIdentity.forget()
+        return
+      }
+      // A new sign-in may belong to a different account. Force the next
+      // storage request to resolve and persist that account's Core identity.
+      // A device-local namespace is remembered first so the data written while
+      // cloud was off can follow the user into the account (see
+      // adoptLocalNamespace).
+      if (event === "SIGNED_IN") {
+        const local = localMiniappUserIdentity.get()
+        if (local && isLocalUserId(local)) pendingLocalNamespace = local
+        localMiniappUserIdentity.forget()
+      }
+      if (!session?.token) return
+      if (connected || reconnectPending) return
+
+      reconnectPending = true
+      console.log(`${LOG_TAG}: auth session available (${event}) while disconnected — reconnecting`)
+      try {
+        cloudClientService.reconnect()
+      } finally {
+        setTimeout(() => {
+          reconnectPending = false
+        }, 0)
+      }
+    })
+
+    const unsub = extractUnsubscribe(sub)
+    if (unsub) authStateUnsubscribe = unsub
+  } catch (err) {
+    console.warn(`${LOG_TAG}: auth watch subscribe failed: ${(err as Error)?.message ?? err}`)
+  }
+}
+
+function stopAuthWatch(): void {
+  authStateUnsubscribe?.()
+  authStateUnsubscribe = null
+}
+
+function emitTranscript(data: TranscriptionData): void {
+  for (const l of transcriptListeners) {
+    try {
+      l(data)
+    } catch (err) {
+      console.warn(`${LOG_TAG}: transcript listener threw: ${(err as Error)?.message ?? err}`)
+    }
+  }
+}
+
+function emitTranslation(data: TranslationData): void {
+  for (const l of translationListeners) {
+    try {
+      l(data)
+    } catch (err) {
+      console.warn(`${LOG_TAG}: translation listener threw: ${(err as Error)?.message ?? err}`)
+    }
+  }
+}
+
+function emitQuota(data: QuotaStatusPayload): void {
+  for (const l of quotaListeners) {
+    try {
+      l(data)
+    } catch (err) {
+      console.warn(`${LOG_TAG}: quota listener threw: ${(err as Error)?.message ?? err}`)
+    }
+  }
+}
+
+function emitStatus(snapshot: CloudClientStatusSnapshot): void {
+  for (const l of statusListeners) {
+    try {
+      l(snapshot)
+    } catch (err) {
+      console.warn(`${LOG_TAG}: status listener threw: ${(err as Error)?.message ?? err}`)
+    }
+  }
+}
+
+function ensureTransports(): void {
+  if (transportsReady) return
+  transportsReady = true
+  setNativeUdp(() => createCloudUdpSocket())
+  setSecureStorage(cloudSecureStore)
+  if (Platform.OS !== "android") return
+  setNativeHttp(async (input, init) => {
+    if (typeof input !== "string" || (init?.body != null && typeof init.body !== "string")) {
+      return globalThis.fetch(input, init)
+    }
+    const headers = Object.fromEntries(new Headers(init?.headers).entries())
+    const result = await CrustModule.nativeHttpRequest(
+      init?.method ?? "GET",
+      input,
+      headers,
+      (init?.body as string | undefined) ?? null,
+    )
+    return new Response(nativeHttpResponseBody(result.status, result.body), {
+      status: result.status,
+      statusText: result.statusText,
+      headers: result.headers,
+    })
+  })
+}
+
+function clearRuntimeEventSubscriptions(): void {
+  runtimeStatusUnsubscribe?.()
+  runtimeStatusUnsubscribe = null
+  transcriptUnsubscribe?.()
+  transcriptUnsubscribe = null
+  translationUnsubscribe?.()
+  translationUnsubscribe = null
+  quotaUnsubscribe?.()
+  quotaUnsubscribe = null
+}
+
+/**
+ * The user's hard "never talk to Glassly cloud" stance (Settings > Privacy).
+ * Read imperatively at every would-be-connect point rather than cached, so
+ * flipping the toggle takes effect without a restart. `=== true` because
+ * getSetting is `any` and an unhydrated store must not read as "disabled".
+ */
+function cloudDisabled(): boolean {
+  return useSettingsStore.getState().getSetting(SETTINGS.disable_cloud.key) === true
+}
+
+function startLc3FrameSizeWatcher(): void {
+  if (lc3FrameSizeUnsubscribe) return
+
+  let last = frameSizeBytes()
+  lc3FrameSizeUnsubscribe = useSettingsStore.subscribe(
+    (state) => state.getSetting(SETTINGS.lc3_frame_size.key),
+    () => {
+      const next = frameSizeBytes()
+      if (next === last) return
+      last = next
+      if (!client) return
+      console.log(`${LOG_TAG}: LC3 frame size changed to ${next}; reconnecting runtime`)
+      cloudClientService.reconnect()
+    },
+  )
+}
+
+function stopLc3FrameSizeWatcher(): void {
+  lc3FrameSizeUnsubscribe?.()
+  lc3FrameSizeUnsubscribe = null
+}
+
+/**
+ * Apply a mid-session flip of the Privacy toggle without a restart: turning it
+ * on tears the live client down, turning it back off reconnects. Installed by
+ * init() on BOTH branches — when cloud starts disabled there is no client to
+ * hang the watcher off, but we still need to notice the user re-enabling it.
+ */
+function startDisableCloudWatcher(): void {
+  if (disableCloudUnsubscribe) return
+
+  let last = cloudDisabled()
+  disableCloudUnsubscribe = useSettingsStore.subscribe(
+    (state) => state.getSetting(SETTINGS.disable_cloud.key),
+    () => {
+      const next = cloudDisabled()
+      if (next === last) return
+      last = next
+      if (next) {
+        console.log(`${LOG_TAG}: cloud disabled — tearing down client`)
+        cloudClientService.stop()
+      } else {
+        console.log(`${LOG_TAG}: cloud re-enabled — reconnecting`)
+        cloudClientService.init()
+      }
+    },
+  )
+}
+
+function stopDisableCloudWatcher(): void {
+  disableCloudUnsubscribe?.()
+  disableCloudUnsubscribe = null
+}
+
+function construct(): void {
+  ensureTransports()
+
+  const endpoints = resolveEndpoints()
+  console.log(`${LOG_TAG}: endpoints ${JSON.stringify(endpoints)}`)
+
+  const coreAuth = {getSubjectToken}
+  const auth = shouldUseLocalDevRuntimeToken(endpoints)
+    ? {
+        core: coreAuth,
+        runtime: {getToken: (opts?: {forceRefresh?: boolean}) => getLocalDevRuntimeToken(endpoints.runtime, opts)},
+      }
+    : {core: coreAuth, runtime: {source: "core" as const}}
+
+  client = new CloudClient({
+    endpoints,
+    // The phone LC3-encodes mic audio (even in phone/simulated mode); announce
+    // LC3 at 16 kHz with the frame size the encoder emits.
+    audio: {codec: "lc3", sampleRate: 16000, frameSizeBytes: frameSizeBytes()},
+    auth,
+    timers: {
+      setTimeout: (callback, delayMs) => BgTimer.setTimeout(callback, delayMs),
+      clearTimeout: (handle) => BgTimer.clearTimeout(handle as number),
+      setInterval: (callback, intervalMs) => BgTimer.setInterval(callback, intervalMs),
+      clearInterval: (handle) => BgTimer.clearInterval(handle as number),
+    },
+    logger: cloudLogger,
+  })
+
+  const c = client
+  clearRuntimeEventSubscriptions()
+  runtimeStatusUnsubscribe = c.runtime.onStatusChanged((status) => {
+    if (c !== client) return
+    setRuntimeStatus(status)
+  })
+  transcriptUnsubscribe = c.runtime.onTranscript((data) => {
+    if (c !== client) return
+    logCloudV2TranscriptMetric(data)
+    emitTranscript(data)
+  })
+  translationUnsubscribe = c.runtime.onTranslation((data) => {
+    if (c !== client) return
+    emitTranslation(data)
+  })
+  quotaUnsubscribe = c.runtime.onQuota((data) => {
+    if (c !== client) return
+    emitQuota(data)
+  })
+  setRuntimeStatus(c.runtime.getStatus())
+
+  c.runtime.onConnected(() => {
+    if (c !== client) return
+    connected = true
+    console.log(`${LOG_TAG}: runtime connected`)
+    console.log(`${LOG_TAG}: debug: ws-session-debug connected`)
+    // Cloud is up — cancel any pending persistent-failure alarm and re-arm for the
+    // next outage.
+    clearPersistentFailureAlarm()
+    // Re-apply the authoritative subscription set, including the empty set, so
+    // a fresh phone launch clears any stale server-side audio subscriptions.
+    c.runtime
+      .setSubscriptions(audioSubscriptions)
+      .catch((err) =>
+        console.warn(`${LOG_TAG}: re-applying queued subscriptions failed: ${(err as Error)?.message ?? err}`),
+      )
+    notifyConnectionListeners(true)
+  })
+  c.runtime.onDisconnected((info) => {
+    if (c !== client) return
+    connected = false
+    console.log(`${LOG_TAG}: runtime disconnected (${info.reason})`)
+    console.log(
+      `${LOG_TAG}: debug: ws-session-debug disconnected reason=${info.reason} willStayDown=${/superseded by newer session/i.test(info.reason)}`,
+    )
+    // Arm the persistent-failure alarm once; if we're still down when it fires, raise
+    // the notification. A reconnect within the window cancels it (onConnected above).
+    if (!persistentFailureTimer && !persistentFailureNotified) {
+      persistentFailureTimer = BgTimer.setTimeout(() => {
+        persistentFailureTimer = null
+        if (connected) return
+        persistentFailureNotified = true
+        islandNotifications.emit({
+          kind: "connection_failed_persistent",
+          reason: `Cloud session has been disconnected for over ${Math.round(CLOUD_PERSISTENT_FAILURE_MS / 1000)}s`,
+          metadata: {downForMs: CLOUD_PERSISTENT_FAILURE_MS, lastReason: info.reason},
+          timestamp: Date.now(),
+        })
+      }, CLOUD_PERSISTENT_FAILURE_MS)
+    }
+    notifyConnectionListeners(false)
+  })
+  c.runtime.onError((err) => {
+    console.warn(`${LOG_TAG}: runtime error: ${err.code}`)
+  })
+
+  // Dead credentials (refresh AND subject exchange both failed). Surface to
+  // the host so it can force a re-login — otherwise the app looks signed-in
+  // while every cloud feature silently fails. Fires at most once per client
+  // instance (the auth module latches until a successful exchange).
+  c.auth.onExpired(() => {
+    if (c !== client) return
+    console.warn(`${LOG_TAG}: cloud session expired beyond recovery — notifying host`)
+    getAuth()?.onSessionExpired?.()
+  })
+
+  // Best-effort connect. Do not crash the app if the dev cloud is unreachable.
+  c.runtime
+    .connect()
+    .then(() => console.log(`${LOG_TAG}: connect() resolved`))
+    .catch((err) => console.warn(`${LOG_TAG}: connect() failed: ${err?.message ?? err}`))
+
+  syncCoreAccessTokenToBluetooth().catch((err) =>
+    console.warn(`${LOG_TAG}: initial Bluetooth core_token sync failed: ${(err as Error)?.message ?? err}`),
+  )
+
+  startLc3FrameSizeWatcher()
+}
+
+/**
+ * engine's cloud client. Owns the singleton CloudClient, its connection state,
+ * and the runtime-hook wiring.
+ */
+export const cloudClientService = {
+  /**
+   * Construct (once) + connect the client. Idempotent. Best-effort connect — a
+   * failure is logged and the app keeps running. Requires
+   * `engine.configure({auth, config})` first.
+   */
+  init(): void {
+    if (client) return
+    // Privacy stance wins over every caller, including the lazy `if (!client)
+    // this.init()` paths below — this is the one chokepoint where the client
+    // gets built, so refusing here keeps the socket from ever opening.
+    if (cloudDisabled()) {
+      console.log(`${LOG_TAG}: init skipped — cloud disabled in Privacy settings`)
+      startDisableCloudWatcher()
+      return
+    }
+    ensureAuthWatch()
+    startDisableCloudWatcher()
+    construct()
+  },
+
+  /** True when the user has turned Glassly cloud off entirely. */
+  isCloudDisabled(): boolean {
+    return cloudDisabled()
+  },
+
+  /**
+   * Tear down + rebuild. Pass new endpoints to switch URLs; pass `null` to CLEAR
+   * a prior override and fall back to the boot config (so cleared/default cloud
+   * URLs don't keep reconnecting to a stale override); omit to keep the current.
+   */
+  reconnect(endpoints?: {core: string; runtime: string} | null): void {
+    const prevCore = resolveEndpoints().core
+    if (endpoints !== undefined) endpointsOverride = endpoints
+    // Tokens are minted per backend (per-env signing keys + user DB), so a
+    // core switch makes the persisted refresh token dead weight the new
+    // backend will reject. Drop it so the client goes straight to a subject
+    // exchange instead of burning a round trip on a guaranteed invalid_grant.
+    // Key literal matches cloud-client's token-store.ts REFRESH_TOKEN_KEY.
+    if (resolveEndpoints().core !== prevCore) {
+      console.log(`${LOG_TAG}: core endpoint changed — dropping persisted cloud refresh token`)
+      void cloudSecureStore.delete("glassly.cloud-client.refreshToken")
+    }
+    try {
+      client?.runtime.close()
+    } catch (err) {
+      console.warn(`${LOG_TAG}: reconnect close() failed: ${(err as Error)?.message ?? err}`)
+    }
+    clearRuntimeEventSubscriptions()
+    clearPersistentFailureAlarm()
+
+    const wasConnected = connected
+    client = null
+    localDevRuntimeToken = null
+    connected = false
+    resetRuntimeStatus()
+    if (wasConnected) notifyConnectionListeners(false)
+
+    // Same gate as init(): endpoint changes / LC3 reconnects must not resurrect
+    // a connection the user has switched off.
+    if (cloudDisabled()) {
+      console.log(`${LOG_TAG}: reconnect skipped — cloud disabled in Privacy settings`)
+      return
+    }
+    construct()
+  },
+
+  async getPreinstalledMiniappRegistry(): Promise<PreinstalledMiniappRegistry> {
+    if (!client) this.init()
+    const c = client
+    if (!c?.core) throw new Error("cloud client core is unavailable")
+    return c.core.miniapps.getRegistry()
+  },
+
+  /**
+   * Resolve the stable Core-owned Glassly user id.
+   *
+   * Storage must use this identity rather than the short-lived Core access
+   * token. A previously verified id is restored from MMKV so local miniapps
+   * remain available after an offline process restart. On first sign-in,
+   * callers join the auth module's single-flight exchange/refresh instead of
+   * falling back to an anonymous namespace.
+   */
+  async resolveGlasslyUserId(): Promise<string> {
+    // With cloud off there is no client to exchange a token with and never will
+    // be, so the online path below would throw on every storage call and take
+    // offline-capable local miniapps down with it. Fall back to a device-local
+    // namespace instead — a cached Core id still wins inside resolveLocal().
+    if (cloudDisabled()) return localMiniappUserIdentity.resolveLocal()
+
+    return localMiniappUserIdentity.resolve(async () => {
+      if (!client) this.init()
+      const c = client
+      if (!c) throw new Error("cloud client not initialized")
+
+      await c.auth.getCoreToken()
+      if (c !== client) throw new Error("cloud client changed while resolving user identity")
+      // Runs before resolve() persists the id, so the local namespace is adopted
+      // whichever path reaches Core identity first (this or the token sync).
+      adoptLocalNamespace(c.auth.identity.glasslyUserId)
+      return c.auth.identity.glasslyUserId
+    })
+  },
+
+  /** Read the stable Glassly user id after async identity resolution. */
+  getGlasslyUserId(): string {
+    // Mirrors resolveGlasslyUserId(): with cloud off, minting is synchronous and
+    // cannot fail, so sync callers (BlobStore) don't depend on an async resolve
+    // having run first.
+    if (cloudDisabled()) return localMiniappUserIdentity.resolveLocal()
+    const userId = localMiniappUserIdentity.get()
+    if (!userId) throw new Error("Glassly user identity is unavailable")
+    return userId
+  },
+
+  async getMiniappAuthToken(
+    packageName: string,
+    opts?: {minTtlMs?: number; devAttestation?: string},
+  ): Promise<MiniappAuthToken> {
+    if (!client) this.init()
+    const c = client
+    if (!c) throw new Error("cloud client not initialized")
+
+    const {token, expiresAt} = await c.auth.getMiniappToken(packageName, opts)
+    const identity = c.auth.identity
+    return {
+      glasslyUserId: identity.glasslyUserId,
+      tenantId: identity.tenantId,
+      token,
+      expiresAt: normalizeExpiresAt(expiresAt),
+    }
+  },
+
+  /**
+   * Tear down the client + connection (the engine.stop() lifecycle).
+   *
+   * Deliberately leaves the disable-cloud watcher installed: this is also the
+   * teardown the Privacy toggle triggers, and dropping the subscription here
+   * would strand the app disconnected until restart when the user flips the
+   * toggle back off. `shutdown()` is the full-stop variant that removes it.
+   */
+  stop(): void {
+    try {
+      client?.runtime.close()
+    } catch (err) {
+      console.warn(`${LOG_TAG}: stop close() failed: ${(err as Error)?.message ?? err}`)
+    }
+    stopLc3FrameSizeWatcher()
+    stopAuthWatch()
+    clearRuntimeEventSubscriptions()
+    clearPersistentFailureAlarm()
+    const wasConnected = connected
+    client = null
+    // stop() is part of the logout lifecycle and runs before the host emits
+    // SIGNED_OUT. Remove the persisted namespace owner here so a later account
+    // can never inherit it. A force-stop/process kill does not call stop(), so
+    // the cached id still survives the offline cold-start case.
+    localMiniappUserIdentity.forget()
+    localDevRuntimeToken = null
+    connected = false
+    resetRuntimeStatus()
+    if (wasConnected) notifyConnectionListeners(false)
+  },
+
+  /** `stop()` plus the disable-cloud watcher — for a genuine engine teardown. */
+  shutdown(): void {
+    this.stop()
+    stopDisableCloudWatcher()
+  },
+
+  /** Device-side managed photo (cloud-v2): presign now, deliver bytes, await ready. */
+  startManagedPhoto(opts: Record<string, unknown> = {}) {
+    if (!client) throw new Error("cloud client not connected")
+    return client.runtime.startManagedPhoto(opts)
+  },
+  awaitManagedPhotoReady(requestId: string) {
+    if (!client) throw new Error("cloud client not connected")
+    return client.runtime.awaitManagedPhotoReady(requestId)
+  },
+
+  /** Managed stream (cloud-v2): provision ingest+playback on the runtime. */
+  startManagedStream(opts: Record<string, unknown> = {}) {
+    if (!client) throw new Error("cloud client not connected")
+    return client.runtime.startManagedStream(opts)
+  },
+  getManagedStreamStatus(streamId: string) {
+    if (!client) throw new Error("cloud client not connected")
+    return client.runtime.getManagedStreamStatus(streamId)
+  },
+  stopManagedStream(streamId: string) {
+    if (!client) throw new Error("cloud client not connected")
+    return client.runtime.stopManagedStream(streamId)
+  },
+
+  /** Current live-session connection state (handshake completed). */
+  isConnected(): boolean {
+    return connected
+  },
+
+  /** Subscribe to connection-state transitions. Returns an unsubscribe fn. */
+  onConnectionChange(listener: (connected: boolean) => void): () => void {
+    connectionListeners.add(listener)
+    return () => {
+      connectionListeners.delete(listener)
+    }
+  },
+
+  /** Replace the v2 cloud's audio subscription set for the live session. */
+  async setSubscriptions(subs: AudioSubscription[]): Promise<void> {
+    // Cache unconditionally so the desired set survives a not-yet-connected
+    // session and reconnects; the onConnected handler re-applies the cached set.
+    audioSubscriptions = subs
+    const c = client
+    if (connected && c) {
+      await c.runtime.setSubscriptions(subs)
+    }
+  },
+
+  sendAudioFrame(frame: Uint8Array): void {
+    client?.runtime.sendAudioFrame(frame)
+  },
+
+  onTranscript(cb: (d: TranscriptionData) => void): () => void {
+    transcriptListeners.add(cb)
+    return () => {
+      transcriptListeners.delete(cb)
+    }
+  },
+
+  onTranslation(cb: (d: TranslationData) => void): () => void {
+    translationListeners.add(cb)
+    return () => {
+      translationListeners.delete(cb)
+    }
+  },
+
+  /** Plan-quota block/unblock pushes for metered cloud streams. */
+  onQuota(cb: (d: QuotaStatusPayload) => void): () => void {
+    quotaListeners.add(cb)
+    return () => {
+      quotaListeners.delete(cb)
+    }
+  },
+
+  getStatus(): CloudClientStatusSnapshot {
+    return currentRuntimeStatus()
+  },
+
+  getCoreUrl(): string {
+    return resolveEndpoints().core
+  },
+
+  syncCoreTokenToBluetooth(): Promise<string> {
+    return syncCoreAccessTokenToBluetooth()
+  },
+
+  onStatusChanged(cb: (snapshot: CloudClientStatusSnapshot) => void): () => void {
+    statusListeners.add(cb)
+    return () => {
+      statusListeners.delete(cb)
+    }
+  },
+
+  tts: {
+    speak(text: string, options?: Parameters<CloudClient["runtime"]["tts"]["speak"]>[1]) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.tts.speak(text, options)
+    },
+  },
+
+  llm: {
+    /**
+     * One completion turn through the cloud LLM service. `userApiKey` is the
+     * user's own provider key when they've saved one; the cloud bills that key
+     * instead of the platform's and skips metering. It rides as a header, never
+     * in the request body.
+     */
+    complete(
+      req: Parameters<CloudClient["runtime"]["llm"]["complete"]>[0],
+      opts?: Parameters<CloudClient["runtime"]["llm"]["complete"]>[1],
+    ) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.llm.complete(req, opts)
+    },
+
+    /** One agentic visual-generation run. Long-running; see cloud-client docs. */
+    generate(
+      req: Parameters<CloudClient["runtime"]["llm"]["generate"]>[0],
+      opts?: Parameters<CloudClient["runtime"]["llm"]["generate"]>[1],
+    ) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.llm.generate(req, opts)
+    },
+
+    /** Start a pollable generate job (async flavor; 404 on old clouds). */
+    startGenerateJob(
+      req: Parameters<CloudClient["runtime"]["llm"]["startGenerateJob"]>[0],
+      opts?: Parameters<CloudClient["runtime"]["llm"]["startGenerateJob"]>[1],
+    ) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.llm.startGenerateJob(req, opts)
+    },
+
+    generateJobStatus(jobId: string) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.llm.generateJobStatus(jobId)
+    },
+
+    cancelGenerateJob(jobId: string) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.llm.cancelGenerateJob(jobId)
+    },
+  },
+
+  maps: {
+    directions(req: Parameters<CloudClient["runtime"]["maps"]["directions"]>[0]) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.maps.directions(req)
+    },
+    reverseGeocode(coord: Parameters<CloudClient["runtime"]["maps"]["reverseGeocode"]>[0]) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.maps.reverseGeocode(coord)
+    },
+    placeAutocomplete(req: Parameters<CloudClient["runtime"]["maps"]["placeAutocomplete"]>[0]) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.maps.placeAutocomplete(req)
+    },
+    placeDetails(req: Parameters<CloudClient["runtime"]["maps"]["placeDetails"]>[0]) {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.maps.placeDetails(req)
+    },
+    /**
+     * The deployment's public map render token ({provider, token}) for the
+     * consumers that can't be proxied (tiles, native nav SDK). `token` null =
+     * this deployment serves none. See MapboxTokenService for the caching
+     * consumer.
+     */
+    renderToken() {
+      if (!client) throw new Error("cloud client not connected")
+      return client.runtime.maps.renderToken()
+    },
+  },
+
+  core: {
+    reports: {
+      submit(...args: Parameters<CloudCore["reports"]["submit"]>) {
+        return getCoreClient().reports.submit(...args)
+      },
+      addLogs(...args: Parameters<CloudCore["reports"]["addLogs"]>) {
+        return getCoreClient().reports.addLogs(...args)
+      },
+      addScreenshots(...args: Parameters<CloudCore["reports"]["addScreenshots"]>) {
+        return getCoreClient().reports.addScreenshots(...args)
+      },
+      complete(...args: Parameters<CloudCore["reports"]["complete"]>) {
+        return getCoreClient().reports.complete(...args)
+      },
+    },
+    supportProfile: {
+      update(...args: Parameters<CloudCore["supportProfile"]["update"]>) {
+        return getCoreClient().supportProfile.update(...args)
+      },
+    },
+  },
+
+  hasAudioSubscriptions(): boolean {
+    return audioSubscriptions.length > 0
+  },
+}