@glassly/engine 0.1.0-dev.0

package/build/services/CloudClientService.js

@@ -0,0 +1,965 @@
+/**
+ * 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 { Platform } from "react-native";
+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 { 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 } from "./LocalMiniappDataMigration";
+import { nativeHttpResponseBody } from "./NativeHttpResponse";
+const LOG_TAG = "cloudClient";
+// 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() {
+    if (persistentFailureTimer) {
+        BgTimer.clearTimeout(persistentFailureTimer);
+        persistentFailureTimer = null;
+    }
+    persistentFailureNotified = false;
+}
+// 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 = null;
+let connected = false;
+let persistentFailureTimer = null;
+let persistentFailureNotified = false;
+let audioSubscriptions = [];
+let transportsReady = false;
+/** Endpoints to build with — seeded from config, overridable via reconnect(). */
+let endpointsOverride = null;
+let runtimeStatusUnsubscribe = null;
+let transcriptUnsubscribe = null;
+let translationUnsubscribe = null;
+let quotaUnsubscribe = null;
+let authStateUnsubscribe = null;
+let localDevRuntimeToken = null;
+let lc3FrameSizeUnsubscribe = null;
+let disableCloudUnsubscribe = null;
+let coreTokenSyncPromise = 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 = null;
+let blobNamespaceMigrator = 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 = migrator;
+}
+/** Result-free view of MMKV, as the migration's plain get/set/remove/keys. */
+const migrationBackend = {
+    get(key) {
+        const result = mmkvStorage.load(key);
+        return result.is_ok() ? result.value : null;
+    },
+    set(key, value) {
+        const result = mmkvStorage.save(key, value);
+        if (result.is_error())
+            throw result.error;
+    },
+    remove(key) {
+        const result = mmkvStorage.remove(key);
+        if (result.is_error())
+            throw result.error;
+    },
+    keys() {
+        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) {
+    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?.message ?? err}`);
+    }
+}
+const localMiniappUserIdentity = new LocalMiniappUserIdentity({
+    get() {
+        const result = mmkvStorage.load(LOCAL_MINIAPP_USER_ID_KEY);
+        return result.is_ok() ? result.value : null;
+    },
+    set(userId) {
+        const result = mmkvStorage.save(LOCAL_MINIAPP_USER_ID_KEY, userId);
+        if (result.is_error())
+            throw result.error;
+    },
+    remove() {
+        const result = mmkvStorage.remove(LOCAL_MINIAPP_USER_ID_KEY);
+        if (result.is_error())
+            throw result.error;
+    },
+});
+const transcriptListeners = new Set();
+const translationListeners = new Set();
+const quotaListeners = new Set();
+const statusListeners = new Set();
+const connectionListeners = new Set();
+function resolveEndpoints() {
+    if (endpointsOverride)
+        return endpointsOverride;
+    const cfg = getConfigValues();
+    return {
+        core: cfg.coreUrl?.trim() || FALLBACK_CORE_URL,
+        runtime: cfg.runtimeUrl?.trim() || FALLBACK_RUNTIME_URL,
+    };
+}
+function getCoreClient() {
+    if (!client)
+        construct();
+    const core = client?.core;
+    if (!core)
+        throw new Error("cloud client core not configured");
+    return core;
+}
+function syncCoreAccessTokenToBluetooth() {
+    if (coreTokenSyncPromise)
+        return coreTokenSyncPromise;
+    coreTokenSyncPromise = syncCoreAccessTokenToBluetoothInternal().finally(() => {
+        coreTokenSyncPromise = null;
+    });
+    return coreTokenSyncPromise;
+}
+async function syncCoreAccessTokenToBluetoothInternal() {
+    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?.message ?? err}`);
+    }
+    return token;
+}
+function frameSizeBytes() {
+    // 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() {
+    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 };
+}
+function normalizeExpiresAt(expiresAt) {
+    return expiresAt < 10_000_000_000 ? expiresAt * 1000 : expiresAt;
+}
+function shouldUseLocalDevRuntimeToken(endpoints) {
+    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, opts) {
+    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());
+    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) {
+    return { status: snapshot.status, audioTransport: snapshot.audioTransport };
+}
+function currentRuntimeStatus() {
+    const state = useCloudClientStatusStore.getState();
+    return { status: state.status, audioTransport: state.audioTransport };
+}
+function setRuntimeStatus(snapshot) {
+    useCloudClientStatusStore.getState().setSnapshot(snapshot);
+    emitStatus(toCloudClientStatusSnapshot(snapshot));
+}
+function resetRuntimeStatus() {
+    useCloudClientStatusStore.getState().reset();
+    emitStatus(currentRuntimeStatus());
+}
+function stringifyMeta(meta) {
+    if (!meta || typeof meta !== "object")
+        return "";
+    try {
+        return ` ${JSON.stringify(meta)}`;
+    }
+    catch {
+        return "";
+    }
+}
+const cloudLogger = {
+    debug: (msg, meta) => console.log(`${LOG_TAG}: debug: ${msg}${stringifyMeta(meta)}`),
+    info: (msg, meta) => console.log(`${LOG_TAG}: info: ${msg}${stringifyMeta(meta)}`),
+    warn: (msg, meta) => console.warn(`${LOG_TAG}: warn: ${msg}${stringifyMeta(meta)}`),
+    error: (msg, meta) => console.warn(`${LOG_TAG}: error: ${msg}${stringifyMeta(meta)}`),
+};
+function notifyConnectionListeners(next) {
+    for (const l of connectionListeners) {
+        try {
+            l(next);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: connection listener threw: ${err?.message ?? err}`);
+        }
+    }
+}
+function extractUnsubscribe(sub) {
+    const candidates = [];
+    const s = sub;
+    if (s && typeof s === "object") {
+        candidates.push(s);
+        candidates.push(s.value?.subscription);
+        candidates.push(s.data?.subscription);
+        candidates.push(s.subscription);
+    }
+    for (const c of candidates) {
+        const unsub = c?.unsubscribe;
+        if (typeof unsub === "function")
+            return unsub;
+    }
+    return null;
+}
+function ensureAuthWatch() {
+    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?.message ?? err}`);
+    }
+}
+function stopAuthWatch() {
+    authStateUnsubscribe?.();
+    authStateUnsubscribe = null;
+}
+function emitTranscript(data) {
+    for (const l of transcriptListeners) {
+        try {
+            l(data);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: transcript listener threw: ${err?.message ?? err}`);
+        }
+    }
+}
+function emitTranslation(data) {
+    for (const l of translationListeners) {
+        try {
+            l(data);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: translation listener threw: ${err?.message ?? err}`);
+        }
+    }
+}
+function emitQuota(data) {
+    for (const l of quotaListeners) {
+        try {
+            l(data);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: quota listener threw: ${err?.message ?? err}`);
+        }
+    }
+}
+function emitStatus(snapshot) {
+    for (const l of statusListeners) {
+        try {
+            l(snapshot);
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: status listener threw: ${err?.message ?? err}`);
+        }
+    }
+}
+function ensureTransports() {
+    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 ?? null);
+        return new Response(nativeHttpResponseBody(result.status, result.body), {
+            status: result.status,
+            statusText: result.statusText,
+            headers: result.headers,
+        });
+    });
+}
+function clearRuntimeEventSubscriptions() {
+    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() {
+    return useSettingsStore.getState().getSetting(SETTINGS.disable_cloud.key) === true;
+}
+function startLc3FrameSizeWatcher() {
+    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() {
+    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() {
+    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() {
+    disableCloudUnsubscribe?.();
+    disableCloudUnsubscribe = null;
+}
+function construct() {
+    ensureTransports();
+    const endpoints = resolveEndpoints();
+    console.log(`${LOG_TAG}: endpoints ${JSON.stringify(endpoints)}`);
+    const coreAuth = { getSubjectToken };
+    const auth = shouldUseLocalDevRuntimeToken(endpoints)
+        ? {
+            core: coreAuth,
+            runtime: { getToken: (opts) => getLocalDevRuntimeToken(endpoints.runtime, opts) },
+        }
+        : { core: coreAuth, runtime: { source: "core" } };
+    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),
+            setInterval: (callback, intervalMs) => BgTimer.setInterval(callback, intervalMs),
+            clearInterval: (handle) => BgTimer.clearInterval(handle),
+        },
+        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?.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?.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() {
+        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() {
+        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) {
+        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?.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() {
+        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() {
+        // 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() {
+        // 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, opts) {
+        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() {
+        try {
+            client?.runtime.close();
+        }
+        catch (err) {
+            console.warn(`${LOG_TAG}: stop close() failed: ${err?.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() {
+        this.stop();
+        stopDisableCloudWatcher();
+    },
+    /** Device-side managed photo (cloud-v2): presign now, deliver bytes, await ready. */
+    startManagedPhoto(opts = {}) {
+        if (!client)
+            throw new Error("cloud client not connected");
+        return client.runtime.startManagedPhoto(opts);
+    },
+    awaitManagedPhotoReady(requestId) {
+        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 = {}) {
+        if (!client)
+            throw new Error("cloud client not connected");
+        return client.runtime.startManagedStream(opts);
+    },
+    getManagedStreamStatus(streamId) {
+        if (!client)
+            throw new Error("cloud client not connected");
+        return client.runtime.getManagedStreamStatus(streamId);
+    },
+    stopManagedStream(streamId) {
+        if (!client)
+            throw new Error("cloud client not connected");
+        return client.runtime.stopManagedStream(streamId);
+    },
+    /** Current live-session connection state (handshake completed). */
+    isConnected() {
+        return connected;
+    },
+    /** Subscribe to connection-state transitions. Returns an unsubscribe fn. */
+    onConnectionChange(listener) {
+        connectionListeners.add(listener);
+        return () => {
+            connectionListeners.delete(listener);
+        };
+    },
+    /** Replace the v2 cloud's audio subscription set for the live session. */
+    async setSubscriptions(subs) {
+        // 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) {
+        client?.runtime.sendAudioFrame(frame);
+    },
+    onTranscript(cb) {
+        transcriptListeners.add(cb);
+        return () => {
+            transcriptListeners.delete(cb);
+        };
+    },
+    onTranslation(cb) {
+        translationListeners.add(cb);
+        return () => {
+            translationListeners.delete(cb);
+        };
+    },
+    /** Plan-quota block/unblock pushes for metered cloud streams. */
+    onQuota(cb) {
+        quotaListeners.add(cb);
+        return () => {
+            quotaListeners.delete(cb);
+        };
+    },
+    getStatus() {
+        return currentRuntimeStatus();
+    },
+    getCoreUrl() {
+        return resolveEndpoints().core;
+    },
+    syncCoreTokenToBluetooth() {
+        return syncCoreAccessTokenToBluetooth();
+    },
+    onStatusChanged(cb) {
+        statusListeners.add(cb);
+        return () => {
+            statusListeners.delete(cb);
+        };
+    },
+    tts: {
+        speak(text, options) {
+            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, opts) {
+            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, opts) {
+            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, opts) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.llm.startGenerateJob(req, opts);
+        },
+        generateJobStatus(jobId) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.llm.generateJobStatus(jobId);
+        },
+        cancelGenerateJob(jobId) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.llm.cancelGenerateJob(jobId);
+        },
+    },
+    maps: {
+        directions(req) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.maps.directions(req);
+        },
+        reverseGeocode(coord) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.maps.reverseGeocode(coord);
+        },
+        placeAutocomplete(req) {
+            if (!client)
+                throw new Error("cloud client not connected");
+            return client.runtime.maps.placeAutocomplete(req);
+        },
+        placeDetails(req) {
+            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) {
+                return getCoreClient().reports.submit(...args);
+            },
+            addLogs(...args) {
+                return getCoreClient().reports.addLogs(...args);
+            },
+            addScreenshots(...args) {
+                return getCoreClient().reports.addScreenshots(...args);
+            },
+            complete(...args) {
+                return getCoreClient().reports.complete(...args);
+            },
+        },
+        supportProfile: {
+            update(...args) {
+                return getCoreClient().supportProfile.update(...args);
+            },
+        },
+    },
+    hasAudioSubscriptions() {
+        return audioSubscriptions.length > 0;
+    },
+};
+//# sourceMappingURL=CloudClientService.js.map