@mentra/cloud-client 0.1.0-dev.0 → 3.1.0-dev.10

package/README.md

@@ -0,0 +1,35 @@
+# @mentra/cloud-client
+
+The MentraOS cloud client: connects a device (or a test harness) to the
+MentraOS cloud over the wire protocol defined in
+[`@mentra/cloud-protocol`](https://www.npmjs.com/package/@mentra/cloud-protocol),
+handling the handshake, message envelopes, and per-module message flows
+(camera, audio, maps, reports, …).
+
+Its main consumer is [`@mentra/engine`](https://www.npmjs.com/package/@mentra/engine),
+which lists it as a peer dependency — an app embedding the engine installs
+this package alongside it.
+
+## Install
+
+```sh
+npm install @mentra/cloud-client@dev
+```
+
+> Currently published on the `dev` dist-tag (prerelease channel).
+
+## Entry points
+
+| Import | Use |
+| --- | --- |
+| `@mentra/cloud-client` | platform-neutral core: `CloudClient` plus the public config, transport, and error types (wire-protocol types are deliberately *not* re-exported — import those from `@mentra/cloud-protocol`) |
+| `@mentra/cloud-client/react-native` | React Native transport bindings (used by the engine) |
+| `@mentra/cloud-client/node` | Node transport bindings — requires the optional [`ws`](https://www.npmjs.com/package/ws) peer (`npm i ws`) |
+
+The package ships TypeScript source and targets consumers that compile TS
+themselves (Metro / bundlers / tsc).
+
+## Part of MentraOS
+
+Source lives in the [MentraOS monorepo](https://github.com/Mentra-Community/MentraOS)
+under `cloud-v2/packages/cloud-client`. Issues and contributions welcome there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/cloud-client",
-  "version": "0.1.0-dev.0",
+  "version": "3.1.0-dev.10",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mentra/cloud-protocol": "^0.1.0-dev.0",
+    "@mentra/cloud-protocol": "3.1.0-dev.10",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {
@@ -42,5 +42,17 @@
     "type": "git",
     "url": "git+https://github.com/Mentra-Community/MentraOS.git",
     "directory": "cloud-v2/packages/cloud-client"
+  },
+  "description": "MentraOS cloud client — handshake, envelopes and module message flows over the cloud wire protocol",
+  "keywords": [
+    "mentra",
+    "mentraos",
+    "cloud",
+    "client",
+    "websocket"
+  ],
+  "homepage": "https://github.com/Mentra-Community/MentraOS/tree/dev/cloud-v2/packages/cloud-client#readme",
+  "bugs": {
+    "url": "https://github.com/Mentra-Community/MentraOS/issues"
   }
 }

package/react-native/index.ts

@@ -30,7 +30,7 @@ export class CloudClient extends Base {
 
 // The host wires the phone's native UDP and secure store through these before
 // constructing a client that uses UDP audio or token persistence.
-export { setNativeUdp, setSecureStorage } from "./transports";
+export { setNativeHttp, setNativeUdp, setSecureStorage } from "./transports";
 export type { NativeUdpFactory } from "./transports";
 
 // Re-export the public surface so a host can import everything (types, errors,

package/react-native/transports.ts

@@ -26,6 +26,7 @@ import type {
   WebSocketLike,
   UdpSocketLike,
   KeyValueStore,
+  HttpTransport,
 } from "../src/transports";
 
 /**
@@ -77,8 +78,7 @@ function adaptWebSocket(raw: GlobalWebSocket): WebSocketLike {
       raw.onmessage = (ev: { data: unknown }) => cb(String(ev.data));
     },
     onClose(cb: (info: { code: number; reason: string }) => void): void {
-      raw.onclose = (ev: { code: number; reason: string }) =>
-        cb({ code: ev.code, reason: ev.reason });
+      raw.onclose = (ev: { code: number; reason: string }) => cb({ code: ev.code, reason: ev.reason });
     },
     onError(cb: (err: unknown) => void): void {
       raw.onerror = (ev: unknown) => cb(ev);
@@ -139,6 +139,20 @@ export function setNativeUdp(factory: NativeUdpFactory): void {
  */
 let secureStorage: KeyValueStore | null = null;
 
+let nativeHttp: HttpTransport | null = null;
+
+/** Wire a background-capable native HTTP executor into the phone client. */
+export function setNativeHttp(http: HttpTransport): void {
+  nativeHttp = http;
+}
+
+function makeHttpTransport(): HttpTransport {
+  return (input, init) => {
+    const execute = nativeHttp ?? globalThis.fetch;
+    return execute(input, init);
+  };
+}
+
 /**
  * Wire in the platform's secure storage.
  *
@@ -212,5 +226,6 @@ export function reactNativeTransports(): CloudClientTransports {
     ws: makeWsFactory(),
     udp: makeUdpFactory(),
     storage: makeSecureStorage(),
+    http: makeHttpTransport(),
   };
 }

package/src/client.ts

@@ -20,6 +20,7 @@ import type { CloudClientConfig } from "./config";
 import { createHttpClient } from "./http";
 import { CloudClientError } from "./errors";
 import type { ConnectionInit } from "@mentra/cloud-protocol";
+import { systemTimers } from "./timers";
 
 // The module implementations. Each is owned by another agent under ./modules/**;
 // this file only constructs them, matching the constructor signatures fixed in
@@ -117,18 +118,13 @@ export class CloudClient {
 
     // Reconnect/backoff lives here so the socket's timing is tuned in one spot.
     const reconnect = config.reconnect ?? DEFAULT_RECONNECT;
+    const timers = config.timers ?? systemTimers;
 
     // Resolve the two base addresses. With a proxy set, both route through it;
     // without one, each module talks to its own service directly.
     const { core: coreBase, runtime: runtimeBase, proxy } = config.endpoints;
-    const coreUrl = coreBase
-      ? proxy
-        ? rewriteThroughProxy(coreBase, proxy)
-        : coreBase
-      : undefined;
-    const runtimeUrl = proxy
-      ? rewriteThroughProxy(runtimeBase, proxy)
-      : runtimeBase;
+    const coreUrl = coreBase ? (proxy ? rewriteThroughProxy(coreBase, proxy) : coreBase) : undefined;
+    const runtimeUrl = proxy ? rewriteThroughProxy(runtimeBase, proxy) : runtimeBase;
 
     if (config.auth.core && !coreUrl) {
       throw new CloudClientError("auth.core requires endpoints.core");
@@ -139,17 +135,12 @@ export class CloudClient {
     // (`{ subjectToken, subjectTokenType }`, no `runtime`) gets a clear
     // configuration error instead of an opaque `TypeError` from `"source" in undefined`.
     if (!config.auth.runtime) {
-      throw new CloudClientError(
-        "auth.runtime is required (got a pre-split/flat auth config?)",
-      );
+      throw new CloudClientError("auth.runtime is required (got a pre-split/flat auth config?)");
     }
 
-    const runtimeUsesCore =
-      "source" in config.auth.runtime && config.auth.runtime.source === "core";
+    const runtimeUsesCore = "source" in config.auth.runtime && config.auth.runtime.source === "core";
     if (runtimeUsesCore && (!coreUrl || !config.auth.core)) {
-      throw new CloudClientError(
-        "auth.runtime.source='core' requires endpoints.core and auth.core",
-      );
+      throw new CloudClientError("auth.runtime.source='core' requires endpoints.core and auth.core");
     }
 
     // Build auth FIRST: runtime and core both source their Bearer from it, so it
@@ -160,7 +151,7 @@ export class CloudClient {
     // before any access token exists. It is deliberately Core-only: runtime-only
     // clients never get a fallback that points Core/Auth calls at Runtime.
     const authHttp = coreUrl
-      ? createHttpClient({ baseUrl: coreUrl, logger })
+      ? createHttpClient({ baseUrl: coreUrl, logger, fetch: config.transports.http, timers })
       : undefined;
     const store = new TokenStore({ storage: config.transports.storage });
     const auth = new Auth({
@@ -168,29 +159,35 @@ export class CloudClient {
       store,
       config: config.auth,
       logger,
-      // The form-encoded `/exchange` and `/refresh` calls go through `fetch`
-      // directly (not the JSON `HttpClient`), so Auth needs the core base URL.
+      // Form-encoded `/exchange` and `/refresh` calls are not JSON HttpClient
+      // requests, but still use the host's injected HTTP transport.
       baseUrl: coreUrl,
+      fetch: config.transports.http,
     });
 
     const getRuntimeToken = (): Promise<string> => auth.getRuntimeToken();
     const getCoreToken = (): Promise<string> => auth.getCoreToken();
 
-    const coreHttp = coreUrl && config.auth.core
-      ? createHttpClient({
-          baseUrl: coreUrl,
-          getToken: getCoreToken,
-          logger,
-        })
-      : null;
+    const coreHttp =
+      coreUrl && config.auth.core
+        ? createHttpClient({
+            baseUrl: coreUrl,
+            getToken: getCoreToken,
+            logger,
+            fetch: config.transports.http,
+            timers,
+          })
+        : null;
     const runtimeHttp = createHttpClient({
       baseUrl: runtimeUrl,
       getToken: getRuntimeToken,
       logger,
+      fetch: config.transports.http,
+      timers,
     });
 
     const emitter = new RuntimeEmitter();
-    const subscriptions = new Subscriptions({ http: runtimeHttp });
+    const subscriptions = new Subscriptions({ http: runtimeHttp, timers });
 
     // The handshake payload the connection sends on every (re)open. It is a
     // factory (not a fixed value) so each reconnect re-reads the current defaults
@@ -216,9 +213,7 @@ export class CloudClient {
         sampleRate: config.audio?.sampleRate ?? DEFAULT_AUDIO_SAMPLE_RATE,
         // Only LC3 carries a frame size; the config type forces LC3 hosts to
         // state theirs explicitly (decoder is sized from this — no safe guess).
-        ...(config.audio?.codec === "lc3"
-          ? { frameSizeBytes: config.audio.frameSizeBytes }
-          : {}),
+        ...(config.audio?.codec === "lc3" ? { frameSizeBytes: config.audio.frameSizeBytes } : {}),
         initialSubscriptions: subscriptions.currentSet(),
       },
     });
@@ -230,12 +225,13 @@ export class CloudClient {
       getToken: getRuntimeToken,
       initPayload,
       reconnect,
+      timers,
       onAuthRejected: async () => {
         await auth.getRuntimeToken({ forceRefresh: true });
       },
       logger,
     });
-    const camera = new Camera({ http: runtimeHttp });
+    const camera = new Camera({ http: runtimeHttp, timers });
     const tts = new Tts({ http: runtimeHttp });
     const maps = new Maps({ http: runtimeHttp });
     const audio = new UdpAudio({ udp: config.transports.udp });
@@ -248,6 +244,7 @@ export class CloudClient {
       tts,
       maps,
       audio,
+      timers,
       logger,
       // On a fatal AUTH_EXPIRED at handshake, runtime forces auth to drop its
       // cached access token and refresh; the connection then re-reads the fresh

package/src/config.ts

@@ -9,6 +9,7 @@
  */
 import type { Logger } from "./logger";
 import type { CloudClientTransports } from "./transports";
+import type { CloudClientTimers } from "./timers";
 
 /**
  * The full shape passed to the root `CloudClient`.
@@ -25,6 +26,13 @@ export interface CloudClientConfig {
   endpoints: { core?: string; runtime: string; proxy?: string };
   auth: AuthConfig;
   transports: CloudClientTransports;
+  /**
+   * Scheduler for all delayed client work, including connection/audio
+   * liveness, retries, and request timeouts. React Native hosts must provide
+   * native background timers because ordinary JS timers pause when Android
+   * backgrounds the app.
+   */
+  timers?: CloudClientTimers;
   logger?: Logger;
   // backoff tuning for the live socket; one place so a host can match its fleet
   reconnect?: { baseMs: number; maxMs: number; jitter: boolean };

package/src/http.ts

@@ -14,6 +14,8 @@
  */
 import { HttpError } from "./errors";
 import type { Logger } from "./logger";
+import { systemTimers, type CloudClientTimers } from "./timers";
+import type { HttpTransport } from "./transports";
 
 /**
  * Per-request options.
@@ -56,6 +58,8 @@ export interface CreateHttpClientDeps {
   // default Bearer source, usually cloud.auth.getRuntimeToken/getCoreToken
   getToken?: () => Promise<string>;
   logger: Logger;
+  fetch?: HttpTransport;
+  timers?: CloudClientTimers;
 }
 
 /** How many times to retry a transient failure on an idempotent call. */
@@ -63,11 +67,6 @@ const MAX_RETRIES = 2;
 /** Base backoff in milliseconds; doubles per attempt (250, 500, ...). */
 const RETRY_BASE_MS = 250;
 
-/** Resolve after `ms`, used for retry backoff. */
-function delay(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
 /**
  * Join a base URL and a path without producing a double slash or dropping one.
  *
@@ -82,6 +81,8 @@ function joinUrl(baseUrl: string, path: string): string {
 
 export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
   const { baseUrl, getToken, logger } = deps;
+  const executeFetch = deps.fetch ?? globalThis.fetch;
+  const timers = deps.timers ?? systemTimers;
 
   /**
    * Resolve the Bearer to attach: a per-call override wins, otherwise the
@@ -119,12 +120,12 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
       if (attempt > 0) {
         const backoff = RETRY_BASE_MS * 2 ** (attempt - 1);
         logger.debug("http retrying request", { method, path, attempt });
-        await delay(backoff);
+        await new Promise<void>((resolve) => timers.setTimeout(resolve, backoff));
       }
 
       let res: Response;
       try {
-        res = await fetch(url, { method, headers, body });
+        res = await executeFetch(url, { method, headers, body });
       } catch {
         // Transient network failure: let the loop retry.
         logger.warn("http network error", { method, path, attempt });
@@ -140,11 +141,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
     }
 
     // Exhausted retries on a transient failure.
-    throw new HttpError(
-      `Network request failed: ${method} ${path}`,
-      0,
-      "NETWORK_ERROR",
-    );
+    throw new HttpError(`Network request failed: ${method} ${path}`, 0, "NETWORK_ERROR");
   }
 
   async function requestRaw(
@@ -166,8 +163,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
 
     // GET and DELETE are idempotent by HTTP semantics, so safe to retry; other
     // verbs opt in via the flag.
-    const idempotent =
-      opts?.idempotent ?? (method === "GET" || method === "DELETE" || method === "HEAD");
+    const idempotent = opts?.idempotent ?? (method === "GET" || method === "DELETE" || method === "HEAD");
 
     return await fetchWithRetry({ method, path, headers, body: payload, idempotent });
   }
@@ -182,11 +178,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
     return await parseJson<T>(res);
   }
 
-  async function requestForm<T>(
-    path: string,
-    form: FormData,
-    opts?: ReqOpts,
-  ): Promise<T> {
+  async function requestForm<T>(path: string, form: FormData, opts?: ReqOpts): Promise<T> {
     const bearer = await resolveBearer(opts);
 
     // No Content-Type here: fetch/FormData must generate the multipart
@@ -210,11 +202,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
    * parse failure here because the status is the load-bearing signal and we do
    * not want a malformed error body to mask the real status.
    */
-  async function toHttpError(
-    res: Response,
-    method: string,
-    path: string,
-  ): Promise<HttpError> {
+  async function toHttpError(res: Response, method: string, path: string): Promise<HttpError> {
     let code: string | undefined;
     let detail = "";
     try {
@@ -230,11 +218,7 @@ export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
     } catch {
       // No JSON body, or unparseable: fall back to status alone.
     }
-    return new HttpError(
-      `HTTP ${res.status} on ${method} ${path}${detail}`,
-      res.status,
-      code,
-    );
+    return new HttpError(`HTTP ${res.status} on ${method} ${path}${detail}`, res.status, code);
   }
 
   /**

package/src/index.ts

@@ -32,6 +32,7 @@ export type {
   UdpSocketLike,
   KeyValueStore,
 } from "./transports";
+export type { CloudClientTimers } from "./timers";
 
 // Local error types a host can branch on with `instanceof`.
 export { CloudClientError, HttpError, AuthExpiredError } from "./errors";
@@ -67,4 +68,7 @@ export type {
   ReportTrigger,
   SubmitReportInput,
   SubmitReportResult,
+  SupportConnectionState,
+  SupportProfileUpdateResult,
+  SupportStateInput,
 } from "./modules/core/core";

package/src/modules/auth/auth.ts

@@ -33,6 +33,7 @@ import type {
 } from "../../config";
 import type { HttpClient } from "../../http";
 import type { Logger } from "../../logger";
+import type { HttpTransport } from "../../transports";
 import { AuthExpiredError } from "../../errors";
 import { decodeClaims } from "./jwt";
 import { TokenStore } from "./token-store";
@@ -133,12 +134,14 @@ export class Auth implements AuthModule {
    * Core base URL for the form-encoded `/exchange` and `/refresh` calls.
    *
    * These two endpoints take `application/x-www-form-urlencoded` bodies and
-   * present the subject/refresh token in the body (not as a Bearer), so they go
-   * through `fetch` directly rather than the JSON-only injected `HttpClient`. In
-   * runtime-only mode this is absent by design: Core identity, miniapp token
-   * minting, and miniapp auto-auth are Core-backed features.
+   * present the subject/refresh token in the body (not as a Bearer), so they do
+   * not use the JSON-only `HttpClient`. They still use the host's injected HTTP
+   * transport when one is available. In runtime-only mode this is absent by
+   * design: Core identity, miniapp token minting, and miniapp auto-auth are
+   * Core-backed features.
    */
   private readonly baseUrl?: string;
+  private readonly httpTransport: HttpTransport;
 
   /** Miniapp tokens cached per packageName until near expiry. */
   private readonly miniappCache = new Map<string, MiniappTokenEntry>();
@@ -160,6 +163,7 @@ export class Auth implements AuthModule {
     config: AuthConfig;
     logger: Logger;
     baseUrl?: string;
+    fetch?: HttpTransport;
   }) {
     this.http = deps.http;
     this.store = deps.store;
@@ -167,6 +171,7 @@ export class Auth implements AuthModule {
     this.runtimeConfig = deps.config.runtime;
     this.logger = deps.logger;
     this.baseUrl = deps.baseUrl;
+    this.httpTransport = deps.fetch ?? globalThis.fetch;
   }
 
   /**
@@ -481,7 +486,7 @@ export class Auth implements AuthModule {
    * POST a form-encoded body to a token endpoint and parse the RFC token
    * response.
    *
-   * Uses `fetch` directly (not the injected JSON `HttpClient`) because these
+   * Uses the injected HTTP transport (not the JSON `HttpClient`) because these
    * endpoints require `application/x-www-form-urlencoded` and present the
    * subject/refresh token in the body, not as a Bearer header. We never log the
    * body: it carries a token.
@@ -492,7 +497,7 @@ export class Auth implements AuthModule {
     label: string,
   ): Promise<TokenResponse> {
     const url = this.joinUrl(path);
-    const res = await fetch(url, {
+    const res = await this.httpTransport(url, {
       method: "POST",
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
       body: body.toString(),

package/src/modules/core/core.ts

@@ -26,6 +26,11 @@ import {
   type SubmitReportInput,
   type SubmitReportResult,
 } from "./reports";
+import {
+  SupportProfiles,
+  type SupportProfileUpdateResult,
+  type SupportStateInput,
+} from "./support-profile";
 
 export type {
   AddReportArtifactsResult,
@@ -40,6 +45,11 @@ export type {
   SubmitReportInput,
   SubmitReportResult,
 } from "./reports";
+export type {
+  SupportConnectionState,
+  SupportProfileUpdateResult,
+  SupportStateInput,
+} from "./support-profile";
 
 /**
  * A single miniapp entry as returned by the listing.
@@ -145,10 +155,14 @@ export class Core {
     ): Promise<AddReportArtifactsResult>;
     complete(reportId: string): Promise<{ status: ReportStatus }>;
   };
+  readonly supportProfile: {
+    update(input: SupportStateInput): Promise<SupportProfileUpdateResult>;
+  };
 
   constructor(deps: CoreDeps) {
     const { http } = deps;
     const reports = new Reports({ http });
+    const supportProfiles = new SupportProfiles(http);
 
     this.miniapps = {
       /**
@@ -198,5 +212,8 @@ export class Core {
       addScreenshots: reports.addScreenshots.bind(reports),
       complete: reports.complete.bind(reports),
     };
+    this.supportProfile = {
+      update: supportProfiles.update.bind(supportProfiles),
+    };
   }
 }

package/src/modules/core/support-profile.ts

@@ -0,0 +1,45 @@
+import type {HttpClient} from "../../http"
+
+export type SupportConnectionState = "disconnected" | "scanning" | "connecting" | "bonding" | "connected"
+
+export interface SupportStateInput {
+  observedAt: string
+  host: {
+    appVersion?: string
+    appBuild?: string
+    engineVersion?: string
+    bluetoothSdkVersion?: string
+    phonePlatform: "ios" | "android" | "unknown"
+    phoneModel?: string
+    phoneOsVersion?: string
+    connectionState: SupportConnectionState
+    failureCode?: string
+    failureStage?: string
+  }
+  device?: {
+    /** Sent over TLS for server-side HMAC derivation, then immediately discarded. */
+    hardwareId?: string
+    model?: string
+    androidVersion?: string
+    firmwareVersion?: string
+    mtkFirmwareVersion?: string
+    besFirmwareVersion?: string
+    appVersion?: string
+    buildNumber?: string
+  }
+}
+
+export interface SupportProfileUpdateResult {
+  status: "accepted" | "deduplicated" | "stale"
+  observedAt: string
+}
+
+export class SupportProfiles {
+  constructor(private readonly http: HttpClient) {}
+
+  update(input: SupportStateInput): Promise<SupportProfileUpdateResult> {
+    return this.http.put<SupportProfileUpdateResult>("/api/client/support-profile", input, {
+      idempotent: true,
+    })
+  }
+}

package/src/modules/runtime/camera.ts

@@ -17,6 +17,7 @@
  * docs/issues/004-cloud-client/design.md ("Camera").
  */
 import type { HttpClient } from "../../http";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 import type {
   CloudToClientMessage,
   PhotoOptions,
@@ -48,6 +49,7 @@ export interface PhotoResult {
 
 export interface CameraDeps {
   http: HttpClient;
+  timers?: CloudClientTimers;
 }
 
 /**
@@ -60,17 +62,19 @@ export interface CameraDeps {
 interface Pending<T> {
   resolve: (value: T) => void;
   reject: (err: Error) => void;
-  timer: ReturnType<typeof setTimeout>;
+  timer: unknown;
 }
 
 export class Camera {
   private readonly http: HttpClient;
+  private readonly timers: CloudClientTimers;
 
   /** In-flight photo requests, keyed by the `requestId` the cloud assigned. */
   private readonly pendingPhotos = new Map<string, Pending<PhotoResult>>();
 
   constructor(deps: CameraDeps) {
     this.http = deps.http;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -111,7 +115,7 @@ export class Camera {
   /** Step 2: resolve when the cloud pushes `photo.ready` for the request. */
   awaitPhotoReady(requestId: string): Promise<PhotoResult> {
     return new Promise<PhotoResult>((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const timer = this.timers.setTimeout(() => {
         // Drop the entry first so the rejection cannot race a late push.
         this.pendingPhotos.delete(requestId);
         reject(new Error(`Managed photo ${requestId} timed out`));
@@ -185,7 +189,7 @@ export class Camera {
   private takePending(requestId: string): Pending<PhotoResult> | undefined {
     const pending = this.pendingPhotos.get(requestId);
     if (!pending) return undefined;
-    clearTimeout(pending.timer);
+    this.timers.clearTimeout(pending.timer);
     this.pendingPhotos.delete(requestId);
     return pending;
   }

package/src/modules/runtime/connection.ts

@@ -50,6 +50,7 @@ import {
 } from "@mentra/cloud-protocol";
 import type { WebSocketLike } from "../../transports";
 import type { Logger } from "../../logger";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 
 /** Connection lifecycle, surfaced to the rest of runtime via `onState`. */
 export type ConnectionState = "connecting" | "open" | "closed";
@@ -117,6 +118,7 @@ export interface ConnectionDeps {
   // what rides in the handshake beyond the token it stamps in.
   initPayload: () => ConnectionInit;
   reconnect: { baseMs: number; maxMs: number; jitter: boolean };
+  timers?: CloudClientTimers;
   // Called when the WebSocket upgrade itself is rejected as unauthorized. That
   // happens before a protocol `error` frame can exist, so runtime's normal
   // AUTH_EXPIRED handshake retry cannot see it. The host uses this to invalidate
@@ -164,8 +166,13 @@ function isUnauthorizedUpgrade(reason: string): boolean {
   return /\b401\b|unauthorized/i.test(reason);
 }
 
+function isSupersededByNewerSession(reason: string): boolean {
+  return /superseded by newer session/i.test(reason);
+}
+
 export class Connection {
   private readonly deps: ConnectionDeps;
+  private readonly timers: CloudClientTimers;
 
   // The current socket. Null between connect attempts and after close, so every
   // access guards on it rather than assuming a live socket.
@@ -187,6 +194,11 @@ export class Connection {
   // stop" from "the network dropped".
   private closedByHost = false;
 
+  // True when the cloud closed us with 1012 "superseded by newer session".
+  // Another live socket for this user won; reconnecting would just kill it
+  // and start a two-client fight. Stays down until the host calls open().
+  private replacedByNewerSession = false;
+
   // How many consecutive failed (re)connect attempts, used to grow the backoff.
   // Reset to zero on a successful handshake.
   private reconnectAttempt = 0;
@@ -196,12 +208,12 @@ export class Connection {
   // already armed is a no-op, so the (intentional) double call from `onClose`
   // and from a failed attempt's catch-reschedule can never stack two timers and
   // double the reconnect rate.
-  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectTimer: unknown | null = null;
 
   // The watchdog interval (started in open(), cleared in close()). It is the
   // backstop that revives the reconnect loop if it ever stalls: see
   // `tickWatchdog` and the file header for why a stall is possible at all.
-  private watchdogTimer: ReturnType<typeof setInterval> | null = null;
+  private watchdogTimer: unknown | null = null;
 
   // Mirror of the last state pushed through `setState`, so the watchdog can ask
   // "are we currently closed?" without a separate subscription. The state
@@ -211,8 +223,8 @@ export class Connection {
 
   // Liveness timers. The interval drives the periodic ping; the pong-wait timer
   // is armed when a ping goes out and disarmed when its pong arrives.
-  private pingTimer: ReturnType<typeof setInterval> | null = null;
-  private pongTimer: ReturnType<typeof setTimeout> | null = null;
+  private pingTimer: unknown | null = null;
+  private pongTimer: unknown | null = null;
 
   // While `open()` is awaiting `connection.ack`, these settle that promise. They
   // are cleared the moment the handshake resolves, rejects, or times out, so a
@@ -220,11 +232,12 @@ export class Connection {
   private pendingAck: {
     resolve: (ack: ConnectionAck) => void;
     reject: (err: Error) => void;
-    timer: ReturnType<typeof setTimeout>;
+    timer: unknown;
   } | null = null;
 
   constructor(deps: ConnectionDeps) {
     this.deps = deps;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -237,6 +250,11 @@ export class Connection {
     return this.currentAck;
   }
 
+  /** True after the cloud closed us as the losing socket for this user. */
+  get isReplacedByNewerSession(): boolean {
+    return this.replacedByNewerSession;
+  }
+
   /**
    * Open the socket, run the handshake, and resolve with `connection.ack`.
    *
@@ -248,8 +266,9 @@ export class Connection {
    */
   async open(): Promise<ConnectionAck> {
     // A fresh open() means the host wants the socket up; clear any prior
-    // host-close intent so a later drop reconnects normally.
+    // host-close / superseded intent so a later drop reconnects normally.
     this.closedByHost = false;
+    this.replacedByNewerSession = false;
 
     // A fresh open() is a clean slate: cancel any stale reconnect left over from
     // a previous session, and reset the backoff so we do not start this connect
@@ -277,6 +296,7 @@ export class Connection {
    */
   close(): void {
     this.closedByHost = true;
+    this.replacedByNewerSession = false;
     this.stopLiveness();
     // Cancel any queued reconnect and stop the watchdog: the host wants us down,
     // so neither the loop nor its backstop should bring the socket back up.
@@ -370,7 +390,7 @@ export class Connection {
     // The promise the handshake settles. Wired before the socket can fire any
     // callback so an immediate open/message cannot race ahead of the listener.
     const acked = new Promise<ConnectionAck>((resolve, reject) => {
-      const timer = setTimeout(() => {
+      const timer = this.timers.setTimeout(() => {
         this.pendingAck = null;
         // Close the half-done socket too: a handshake that times out client-
         // side may still COMPLETE server-side moments later, leaving a ghost
@@ -501,7 +521,7 @@ export class Connection {
     this.reconnectAttempt = 0;
 
     if (this.pendingAck) {
-      clearTimeout(this.pendingAck.timer);
+      this.timers.clearTimeout(this.pendingAck.timer);
       const { resolve } = this.pendingAck;
       this.pendingAck = null;
       resolve(ack);
@@ -509,6 +529,9 @@ export class Connection {
 
     this.setState("open");
     this.startLiveness();
+    this.deps.logger.debug("ws-session-debug handshake ok", {
+      sessionId: ack.sessionId,
+    });
   }
 
   /**
@@ -539,6 +562,20 @@ export class Connection {
     this.setState("closed");
 
     const reason = info.reason || `code ${info.code}`;
+    if (isSupersededByNewerSession(reason)) {
+      // Newest-wins on the server. Coming back up here would supersede the
+      // winner, which then reconnects, forever. Stay down until open().
+      this.replacedByNewerSession = true;
+      this.clearReconnectTimer();
+      this.stopWatchdog();
+      this.deps.logger.info("ws-session-debug staying down after supersede", {
+        code: info.code,
+        reason,
+        sessionId: this.currentAck?.sessionId ?? null,
+        reconnectAttempt: this.reconnectAttempt,
+      });
+      return;
+    }
     if (isUnauthorizedUpgrade(reason)) {
       void Promise.resolve(this.deps.onAuthRejected?.())
         .catch((err) => {
@@ -572,6 +609,12 @@ export class Connection {
     // Already a retry queued -> nothing to do. This is the guard that makes the
     // double call from onClose + catch-reschedule (and the watchdog) harmless.
     if (this.reconnectTimer !== null) return;
+    if (this.replacedByNewerSession) {
+      this.deps.logger.debug("ws-session-debug skip reconnect; replaced by newer session", {
+        reason,
+      });
+      return;
+    }
 
     const delay = backoffDelay(this.reconnectAttempt, this.deps.reconnect);
     this.reconnectAttempt += 1;
@@ -581,7 +624,7 @@ export class Connection {
       reason,
     });
 
-    this.reconnectTimer = setTimeout(() => {
+    this.reconnectTimer = this.timers.setTimeout(() => {
       // Null the timer first so this slot is free again: a connect that fails
       // below must be able to schedule the next retry, and the watchdog must see
       // "no reconnect pending" while the attempt is in flight.
@@ -608,7 +651,7 @@ export class Connection {
   /** Cancel a queued reconnect, if any. Safe to call when none is pending. */
   private clearReconnectTimer(): void {
     if (this.reconnectTimer !== null) {
-      clearTimeout(this.reconnectTimer);
+      this.timers.clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
   }
@@ -620,7 +663,7 @@ export class Connection {
    */
   private startWatchdog(): void {
     this.stopWatchdog();
-    this.watchdogTimer = setInterval(
+    this.watchdogTimer = this.timers.setInterval(
       () => this.tickWatchdog(),
       RECONNECT_WATCHDOG_MS,
     );
@@ -629,7 +672,7 @@ export class Connection {
   /** Stop the reconnect watchdog (on host close). */
   private stopWatchdog(): void {
     if (this.watchdogTimer !== null) {
-      clearInterval(this.watchdogTimer);
+      this.timers.clearInterval(this.watchdogTimer);
       this.watchdogTimer = null;
     }
   }
@@ -649,6 +692,7 @@ export class Connection {
     if (
       this.currentState === "closed" &&
       !this.closedByHost &&
+      !this.replacedByNewerSession &&
       this.reconnectTimer === null
     ) {
       this.scheduleReconnect("watchdog: no reconnect pending");
@@ -665,7 +709,7 @@ export class Connection {
    */
   private startLiveness(): void {
     this.stopLiveness();
-    this.pingTimer = setInterval(() => this.sendPing(), PING_INTERVAL_MS);
+    this.pingTimer = this.timers.setInterval(() => this.sendPing(), PING_INTERVAL_MS);
   }
 
   /** Send one liveness ping and arm the pong-wait timer. */
@@ -676,8 +720,8 @@ export class Connection {
     // If a pong-wait timer is already armed, leave it: a single outstanding
     // timeout is enough to catch a dead socket, and re-arming would push the
     // deadline back on every interval.
-    if (this.pongTimer) return;
-    this.pongTimer = setTimeout(() => {
+    if (this.pongTimer !== null) return;
+    this.pongTimer = this.timers.setTimeout(() => {
       // No pong in time. The socket is dead; close it so the close handler runs
       // the reconnect path, rather than reconnecting from here and racing the
       // existing socket's eventual close.
@@ -703,8 +747,8 @@ export class Connection {
 
   /** Stop both liveness timers (on close, reconnect, or teardown). */
   private stopLiveness(): void {
-    if (this.pingTimer) {
-      clearInterval(this.pingTimer);
+    if (this.pingTimer !== null) {
+      this.timers.clearInterval(this.pingTimer);
       this.pingTimer = null;
     }
     this.clearPongTimer();
@@ -712,8 +756,8 @@ export class Connection {
 
   /** Disarm the pong-wait timer (a pong arrived, or liveness is stopping). */
   private clearPongTimer(): void {
-    if (this.pongTimer) {
-      clearTimeout(this.pongTimer);
+    if (this.pongTimer !== null) {
+      this.timers.clearTimeout(this.pongTimer);
       this.pongTimer = null;
     }
   }
@@ -724,7 +768,7 @@ export class Connection {
    */
   private failPendingAck(err: Error): void {
     if (!this.pendingAck) return;
-    clearTimeout(this.pendingAck.timer);
+    this.timers.clearTimeout(this.pendingAck.timer);
     const { reject } = this.pendingAck;
     this.pendingAck = null;
     reject(err);

package/src/modules/runtime/runtime.ts

@@ -34,6 +34,7 @@ import type { Maps, DirectionsRequest, DirectionsResult, LatLng, ReverseGeocodeR
 import type { Tts, RuntimeTtsSpeakOptions, RuntimeTtsSpeechSource } from "./tts";
 import type { UdpAudio } from "./audio-udp";
 import type { RuntimeSnapshot } from "./status";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 
 const UDP_PROBE_INTERVAL_MS = 1_000;
 const UDP_LIVENESS_TIMEOUT_MS = 3_000;
@@ -117,6 +118,7 @@ export interface RuntimeDeps {
   tts: Tts;
   maps: Maps;
   audio: UdpAudio;
+  timers?: CloudClientTimers;
   logger: Logger;
   /**
    * Force `cloud.auth` to drop its cached access token and refresh now.
@@ -142,13 +144,14 @@ export class Runtime implements RuntimeModule {
   public readonly maps: Maps;
   private readonly audio: UdpAudio;
   private readonly logger: Logger;
+  private readonly timers: CloudClientTimers;
   private readonly forceRefreshToken: () => Promise<string>;
   private status: RuntimeSnapshot = {
     status: "disconnected",
     audioTransport: "none",
   };
   private hostClosed = true;
-  private udpProbeTimer: ReturnType<typeof setInterval> | null = null;
+  private udpProbeTimer: unknown | null = null;
   private udpProbeStartedAt = 0;
   private lastUdpAckAt = 0;
 
@@ -179,6 +182,7 @@ export class Runtime implements RuntimeModule {
     this.tts = deps.tts;
     this.maps = deps.maps;
     this.audio = deps.audio;
+    this.timers = deps.timers ?? systemTimers;
     this.logger = deps.logger;
     this.forceRefreshToken = deps.forceRefreshToken;
   }
@@ -302,16 +306,25 @@ export class Runtime implements RuntimeModule {
         // current set (at the current version) to restore live transcription.
         void this.handleReopen();
       } else if (state === "closed") {
+        const superseded = this.connection.isReplacedByNewerSession;
+        const reason = superseded
+          ? "superseded by newer session"
+          : "socket closed";
+        this.logger.debug("ws-session-debug runtime closed", {
+          superseded,
+          hostClosed: this.hostClosed,
+          reason,
+        });
         this.stopUdpLiveness();
         this.updateStatus({
-          status: this.hostClosed
+          status: this.hostClosed || superseded
             ? "disconnected"
             : this.opened
               ? "reconnecting"
               : "connecting",
           audioTransport: "none",
         });
-        this.emitter.emit("disconnected", { reason: "socket closed" });
+        this.emitter.emit("disconnected", { reason });
       }
     });
   }
@@ -513,15 +526,15 @@ export class Runtime implements RuntimeModule {
     this.udpProbeStartedAt = Date.now();
     this.lastUdpAckAt = 0;
     this.sendUdpProbe();
-    this.udpProbeTimer = setInterval(() => {
+    this.udpProbeTimer = this.timers.setInterval(() => {
       this.sendUdpProbe();
       this.checkUdpLiveness();
     }, UDP_PROBE_INTERVAL_MS);
   }
 
   private stopUdpLiveness(): void {
-    if (this.udpProbeTimer) {
-      clearInterval(this.udpProbeTimer);
+    if (this.udpProbeTimer !== null) {
+      this.timers.clearInterval(this.udpProbeTimer);
       this.udpProbeTimer = null;
     }
     this.udpProbeStartedAt = 0;

package/src/modules/runtime/subscriptions.ts

@@ -17,6 +17,7 @@
  * and docs/issues/004-cloud-client/design.md ("Subscriptions").
  */
 import type { HttpClient } from "../../http";
+import { systemTimers, type CloudClientTimers } from "../../timers";
 import type { AudioSubscription } from "@mentra/cloud-protocol";
 
 /** The REST path the cloud exposes for the full-replace subscription write. */
@@ -24,10 +25,12 @@ const SUBSCRIPTIONS_PATH = "/api/audio/subscriptions";
 
 export interface SubscriptionsDeps {
   http: HttpClient;
+  timers?: CloudClientTimers;
 }
 
 export class Subscriptions {
   private readonly http: HttpClient;
+  private readonly timers: CloudClientTimers;
 
   /**
    * The last set we sent. Kept so a reconnect can re-send the exact same set at
@@ -43,6 +46,7 @@ export class Subscriptions {
 
   constructor(deps: SubscriptionsDeps) {
     this.http = deps.http;
+    this.timers = deps.timers ?? systemTimers;
   }
 
   /**
@@ -130,7 +134,7 @@ export class Subscriptions {
 
       const delay = RETRY_DELAYS_MS[attempt];
       if (res.reason !== "stale-session" || delay === undefined) return;
-      await new Promise((resolve) => setTimeout(resolve, delay));
+      await new Promise<void>((resolve) => this.timers.setTimeout(resolve, delay));
     }
   }
 }

package/src/timers.ts

@@ -0,0 +1,23 @@
+/** Timer surface used by every delayed operation in the cloud client. */
+export interface CloudClientTimers {
+  setTimeout(callback: () => void, delayMs: number): unknown;
+  clearTimeout(handle: unknown): void;
+  setInterval(callback: () => void, intervalMs: number): unknown;
+  clearInterval(handle: unknown): void;
+}
+
+/** Default scheduler for Node, Bun, and foreground browser hosts. */
+export const systemTimers: CloudClientTimers = {
+  setTimeout(callback, delayMs) {
+    return setTimeout(callback, delayMs);
+  },
+  clearTimeout(handle) {
+    clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+  setInterval(callback, intervalMs) {
+    return setInterval(callback, intervalMs);
+  },
+  clearInterval(handle) {
+    clearInterval(handle as ReturnType<typeof setInterval>);
+  },
+};

package/src/transports.ts

@@ -54,6 +54,13 @@ export interface KeyValueStore {
   delete(key: string): Promise<void>;
 }
 
+/** Fetch-compatible HTTP executor supplied by hosts that need networking to
+ * outlive their JavaScript UI lifecycle (for example Android foreground services). */
+export type HttpTransport = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1],
+) => ReturnType<typeof fetch>;
+
 /**
  * The bundle of platform pieces handed to the root `CloudClient`.
  *
@@ -65,4 +72,6 @@ export interface CloudClientTransports {
   ws: (url: string) => WebSocketLike;
   udp: () => UdpSocketLike;
   storage: KeyValueStore;
+  /** Falls back to globalThis.fetch when omitted. */
+  http?: HttpTransport;
 }