@glassly/cloud-client 0.1.0-dev.90 → 0.1.0-dev.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glassly/cloud-client",
-  "version": "0.1.0-dev.90",
+  "version": "0.1.0-dev.96",
   "type": "module",
   "main": "./src/index.ts",
   "exports": {
@@ -12,7 +12,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@glassly/cloud-protocol": "0.1.0-dev.90",
+    "@glassly/cloud-protocol": "0.1.0-dev.96",
     "tweetnacl": "^1.0.3"
   },
   "devDependencies": {

package/src/client.ts

@@ -22,9 +22,8 @@ import { CloudClientError } from "./errors";
 import type { ConnectionInit } from "@glassly/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
-// design.md exactly.
+// The module implementations, under ./modules/**. This file only constructs
+// them, matching the constructor signatures fixed in design.md exactly.
 import { Auth } from "./modules/auth/auth";
 import { TokenStore } from "./modules/auth/token-store";
 import { Runtime } from "./modules/runtime/runtime";
@@ -51,12 +50,12 @@ import { Core } from "./modules/core/core";
 const DEFAULT_RECONNECT = { baseMs: 500, maxMs: 5_000, jitter: true };
 
 /**
- * The default audio codec the client announces in the handshake.
+ * The default audio codec the client announces in the handshake when a host
+ * does not set `config.audio.codec`.
  *
- * LC3 at 16 kHz matches the glasses' on-device codec, so the cloud transcribes
- * the same bytes the device captures. A future config knob can override this; for
- * now the handshake announces the device default so audio that starts immediately
- * after connect is decoded correctly.
+ * PCM at 16 kHz needs no frame-size negotiation, so it is the safe default; a
+ * host whose device captures LC3 sets `config.audio.codec = "lc3"` (and the
+ * required `frameSizeBytes`) explicitly.
  */
 const DEFAULT_AUDIO_CODEC = "pcm" as const;
 const DEFAULT_AUDIO_SAMPLE_RATE = 16_000;

package/src/modules/auth/auth.ts

@@ -411,9 +411,9 @@ export class Auth implements AuthModule {
    * dead refresh token will not heal on its own, and retrying would loop.
    *
    * A transient failure — network error, 5xx during a deploy, 429 — keeps
-   * the stored token and propagates as-is. Clearing on those is how a flaky
-   * cold start (the first launch after an app update, typically) used to log
-   * users out of a perfectly healthy session.
+   * the stored token and propagates as-is: clearing on a transient failure
+   * would log out a perfectly healthy session on a flaky cold start (e.g.
+   * first launch after an app update).
    */
   private async refresh(refreshToken: string, opts?: { deferExpired?: boolean }): Promise<string> {
     const body = new URLSearchParams({

package/src/modules/runtime/connection.ts

@@ -12,30 +12,14 @@
  * It never imports a real socket: the platform supplies a `WebSocketLike`
  * factory, so the same code runs on the phone and in a Node/Bun test harness.
  *
- * Reconnect robustness (why the loop is self-sustaining + watchdogged):
- * The reconnect loop used to be driven ONLY by the socket's `onClose` event
- * (`handleClose` -> `scheduleReconnect`), and a scheduled attempt's
- * `connectOnce().catch()` just swallowed the rejection, trusting that a close
- * event would always fire and schedule the next try. That assumption is the
- * bug: a connect attempt can fail WITHOUT ever firing a clean `onClose` -- a
- * transient network/DNS blip mid-handshake, or a `WebSocketLike` transport that
- * emits only `onError` and no `onClose`. When that happens the chain breaks:
- * nothing schedules the next retry, so the client sits SILENTLY disconnected
- * forever until a full app relaunch. We hit this in dev (ADB/Metro flapping
- * wedged the v2 socket; only a cold relaunch recovered it).
- *
- * Three changes close that gap, belt-and-suspenders:
- *   0. A failed initial `open()` now also enters the reconnect loop. Before
- *      this, reconnect was robust only AFTER the first successful session had
- *      dropped; if the app booted while cloud was down, `open()` rejected and no
- *      retry was queued.
- *   1. The scheduled attempt's `.catch()` now reschedules itself, so a failure
- *      that did NOT fire `onClose` still queues the next try. `scheduleReconnect`
- *      is idempotent (guarded by `reconnectTimer`), so the double call from
- *      `onClose` + this catch never stacks two timers.
- *   2. A lightweight watchdog interval revives the loop if some unforeseen path
- *      ever leaves us `closed`, not host-closed, with no reconnect pending. Even
- *      if reasoning (1) misses a case, the watchdog guarantees we never sit dead.
+ * Reconnect must not depend on `onClose`: a connect attempt can fail without
+ * ever firing a clean close (network/DNS blip mid-handshake, or a
+ * `WebSocketLike` transport that emits only `onError`), which would otherwise
+ * leave the client silently disconnected until relaunch. So the loop is driven
+ * from three places: a failed initial `open()`, the scheduled attempt's own
+ * `.catch()`, and a watchdog interval that revives it if we are ever `closed`,
+ * not host-closed, with no reconnect pending. `scheduleReconnect` is idempotent
+ * (guarded by `reconnectTimer`) so the overlapping callers never stack timers.
  *
  * See docs/issues/004-cloud-client/design.md ("src/modules/runtime/connection.ts")
  * and docs/issues/002-cloud-runtime/protocol.md (envelope, handshake, control).