@pickleball/expo-sdk 0.2.0 → 1.0.0

package/src/device-agent/agent.ts

@@ -1,3 +1,4 @@
+import { nextBeatDelayMs, type MqttBeatHealth } from "./beat-policy";
 import type { BootstrapInput } from "../contracts";
 import type { DeviceMetricsSample, LivestreamEngine } from "../engine";
 import { normalizeError } from "../errors";
@@ -19,8 +20,19 @@ export interface DeviceAgentDeviceInfo {
 
 export interface DeviceCommand {
   id: string;
-  type: "start_livestream" | "stop_livestream";
-  payload: { title?: string; visibility?: "public" | "private" };
+  type:
+    | "start_livestream"
+    | "stop_livestream"
+    // standby ↔ live cho phiên đang có — đường thay LiveKit data channel
+    // của goLive khi deliveryMode="device-rtmp".
+    | "publish_livestream"
+    | "unpublish_livestream";
+  payload: {
+    title?: string;
+    visibility?: "public" | "private";
+    /** Arm-từ-xa chế độ giải đấu: phiên standby sẽ đậu vào sân này. */
+    courtRef?: string;
+  };
   expiresAt: number;
 }
 
@@ -30,20 +42,67 @@ export interface DeviceControlSessionGrant {
   convexUrl: string;
 }
 
+/**
+ * Một lần tiến trình app chết trước đó — Android `ApplicationExitInfo`, native
+ * đã quy đổi `reasonName` ("PACKAGE_UPDATED", "CRASH", "ANR", "OTHER"…). Xem
+ * NativeProcessExit của @pickleball/rtmp-native; iOS không có nguồn tương đương.
+ */
+export interface DeviceProcessExit {
+  /** epoch ms lúc chết. */
+  at: number;
+  reason: number;
+  reasonName: string;
+  /** Chuỗi hệ thống, VD "stop com.google.android.webview due to installPackageLI". */
+  description?: string;
+  /** IMPORTANCE_* lúc chết — 100 = đang ở tiền cảnh. */
+  importance?: number;
+  pid?: number;
+}
+
 export interface DeviceHeartbeatBody {
   agentState?: string;
   currentSessionId?: string | null;
   appVersion?: string;
   metrics?: Record<string, number | string>;
+  /**
+   * Hộp đen: lý do các lần tiến trình chết gần đây. App chỉ cần gửi vài nhịp
+   * đầu sau khi mở (server giữ bản mới nhất, ghi idempotent theo mốc).
+   */
+  recentExits?: DeviceProcessExit[];
+  /**
+   * Trạng thái nguồn app tự khai: "rest" = chế độ nghỉ (camera/service đã tắt,
+   * máy đang nguội). Server chỉ ghi khi đổi — dashboard hiện badge "Đang nghỉ".
+   */
+  powerState?: "rest" | "active";
+  /**
+   * Xin tỉ số kèm response beat — CHỈ bật khi kênh MQTT đứt (đường nhanh
+   * plv1/dev/{id}/score câm); MQTT khoẻ mà vẫn xin là server đọc doc tỉ số
+   * mỗi nhịp vô ích.
+   */
+  wantScore?: boolean;
 }
 
+/**
+ * Field app tự gắn thêm vào MỖI heartbeat. Hàm được gọi ngay trước khi gửi,
+ * trả undefined/{} khi không có gì — ném lỗi thì bị nuốt, heartbeat vẫn đi.
+ */
+export type DeviceHeartbeatExtras = Pick<
+  DeviceHeartbeatBody,
+  "recentExits" | "powerState" | "wantScore"
+>;
+
 export interface DeviceAgentTransport {
   register(
     input: BootstrapInput & DeviceAgentDeviceInfo,
   ): Promise<{ deviceId: string; heartbeatIntervalMs: number }>;
-  heartbeat(
-    input: BootstrapInput & DeviceHeartbeatBody,
-  ): Promise<{ controlSession: DeviceControlSessionGrant | null }>;
+  heartbeat(input: BootstrapInput & DeviceHeartbeatBody): Promise<{
+    controlSession: DeviceControlSessionGrant | null;
+    /**
+     * Nhịp server gợi ý cho lượt beat kế (adaptive heartbeat). Optional để
+     * transport/server đời cũ vẫn hợp lệ — thiếu thì agent giữ nhịp nhanh.
+     */
+    beatIntervalMs?: number;
+  }>;
 }
 
 /** Kênh điều khiển realtime — mặc định là Convex websocket (convex-control-channel). */
@@ -90,6 +149,14 @@ export interface DeviceAgentOptions {
   deviceInfo?: DeviceAgentDeviceInfo;
   onRemoteSessionStarted?: (sessionId: string) => void;
   deviceMetrics?: () => Promise<DeviceMetricsSample | null>;
+  /** Field bổ sung cho heartbeat (VD recentExits) — xem DeviceHeartbeatExtras. */
+  heartbeatExtras?: () => DeviceHeartbeatExtras | undefined;
+  /**
+   * Sức khoẻ kênh MQTT của app (kênh nằm ở tầng app, không thuộc SDK). Có
+   * nguồn này VÀ server bật rollout thì nhịp beat giãn 12s → 60s; thiếu nó thì
+   * agent chạy y hệt trước đây. Ném lỗi trong callback được coi như "không có".
+   */
+  mqttHealth?: () => MqttBeatHealth | null;
   /** Factory kênh điều khiển — test truyền fake; mặc định Convex websocket. */
   createControlChannel?: (convexUrl: string) => DeviceControlChannel;
   /** Test hook: nguồn app-state; mặc định react-native AppState. */
@@ -97,8 +164,39 @@ export interface DeviceAgentOptions {
 }
 
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 12_000;
+/**
+ * Nhịp heartbeat khi máy RẢNH và chưa có kênh điều khiển.
+ *
+ * Từng là 4 giây (18/08/2026): lúc đó dashboard là đường điều khiển chính, mà
+ * lệnh chỉ tới được sau khi heartbeat trả về control session để app attach —
+ * ở nhịp 12s, bấm "Gửi lệnh bắt đầu" phải chờ 12 giây rồi báo thất bại dù lệnh
+ * vẫn còn hiệu lực (TTL 60s).
+ *
+ * Đưa về 12 giây vì hai lẽ:
+ *
+ * 1. Điều khiển thực tế đã chuyển sang PSS gọi REST, không còn bấm tay trên
+ *    dashboard. Khe duy nhất còn nhạy nhịp là từ lúc GÁN SÂN tới lúc máy tự
+ *    arm — mà PSS gán sân ở đầu ngày chứ không gán rồi start ngay.
+ * 2. Nhịp 4s là 2 function call mỗi 4 giây MỖI MÁY, chạy suốt ngày đêm kể cả
+ *    khi không ai dùng. Đây là chi phí nền lớn nhất của đường heartbeat.
+ *
+ * Lưu ý: nhịp này CHỈ áp dụng khi máy chưa giữ phiên nào. Camera đã gác sân
+ * luôn có phiên chờ nên xưa nay vẫn đập theo nhịp thường — xem nextBeatDelay().
+ */
+const IDLE_HEARTBEAT_INTERVAL_MS = 12_000;
 const REGISTER_RETRY_BASE_MS = 2_000;
 const REGISTER_RETRY_MAX_MS = 60_000;
+/**
+ * Metrics (RAM, nhiệt, pin, sóng) nhích gần như mỗi lần đo, nên đính vào MỌI
+ * heartbeat là ghi `devices.metricsJson` mỗi nhịp → đánh thức mọi query reactive
+ * đọc bảng devices. Chỉ gửi khi CÓ CHUYỆN đáng báo, hoặc mỗi 5 phút làm mốc
+ * chẩn đoán nền. Heartbeat vẫn đập đều để giữ "online"; chỉ metrics là thưa.
+ */
+const METRICS_BASELINE_MS = 5 * 60_000;
+/** Pin thủng mốc này (đang ≥ mà tụt xuống dưới) → gửi ngay. */
+const METRICS_BATTERY_LOW_PCT = 10;
+/** Pin đổi từ mốc đã gửi ≥ ngần này phần trăm → gửi (bắt tụt/sạc nhanh). */
+const METRICS_BATTERY_DELTA_PCT = 5;
 /** Chỉ các field server chấp nhận (proxy từ chối key lạ trong metrics). */
 const METRIC_FIELDS = [
   "ramFreeMb",
@@ -111,6 +209,8 @@ const METRIC_FIELDS = [
   "linkMbps",
   "rssi",
   "connQuality",
+  "signalPct",
+  "localIp",
 ] as const;
 
 function defaultSubscribeAppState(listener: AppStateListener): () => void {
@@ -142,18 +242,52 @@ function pickMetrics(
   return Object.keys(metrics).length > 0 ? metrics : undefined;
 }
 
+/**
+ * Metrics lần này có đáng gửi so với lần đã gửi không. Hàm thuần để test dễ.
+ * Đáng gửi khi: chưa gửi lần nào; pin vừa THỦNG mốc thấp (đang ≥10% tụt xuống
+ * <10%); pin đổi ≥5% so với mốc đã gửi; đổi mức nhiệt (thermal) hoặc loại mạng.
+ * KHÔNG tính RAM/sóng/nhiệt-độ-pin: chúng nhích liên tục, để mốc 5 phút lo.
+ */
+export function metricsCrossedThreshold(
+  last: Record<string, number | string> | undefined,
+  next: Record<string, number | string>,
+): boolean {
+  if (!last) return true;
+  const b0 = typeof last.batteryPct === "number" ? last.batteryPct : undefined;
+  const b1 = typeof next.batteryPct === "number" ? next.batteryPct : undefined;
+  if (b1 !== undefined) {
+    if (
+      b1 < METRICS_BATTERY_LOW_PCT &&
+      (b0 === undefined || b0 >= METRICS_BATTERY_LOW_PCT)
+    ) {
+      return true;
+    }
+    if (b0 !== undefined && Math.abs(b1 - b0) >= METRICS_BATTERY_DELTA_PCT) {
+      return true;
+    }
+  }
+  if (next.thermal !== last.thermal) return true;
+  if (next.netType !== last.netType) return true;
+  return false;
+}
+
 export class DeviceAgent {
   private readonly options: DeviceAgentOptions;
   private running = false;
   private registered = false;
   private foreground = true;
   private heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS;
+  /** Nhịp server gợi ý ở beat gần nhất — undefined = server chưa nói gì → 12s. */
+  private serverBeatHintMs: number | undefined;
   private timer: ReturnType<typeof setTimeout> | null = null;
   private beatInFlight = false;
   private registerAttempt = 0;
   private unsubscribeAppState: (() => void) | null = null;
 
   private heartbeatFailures = 0;
+  /** Metrics đã gửi lần gần nhất + mốc thời gian, để lọc "chỉ gửi khi đổi". */
+  private lastSentMetrics?: Record<string, number | string>;
+  private lastMetricsSentAt = 0;
   private controlChannel: DeviceControlChannel | null = null;
   private controlSessionId: string | null = null;
   private controlUnsubscribers: Array<() => void> = [];
@@ -198,6 +332,38 @@ export class DeviceAgent {
     }
   }
 
+  /**
+   * Đang có phiên hoặc đã mở kênh điều khiển = lệnh tới qua kênh, nhịp thường
+   * là đủ. Rảnh và chưa có kênh = đang chờ lệnh, đập nhanh cho kịp dashboard.
+   */
+  private nextBeatDelay(): number {
+    const base = this.controlChannel
+      ? this.heartbeatIntervalMs
+      : this.options.engine.getSnapshot().sessionId
+        ? this.heartbeatIntervalMs
+        : Math.min(IDLE_HEARTBEAT_INTERVAL_MS, this.heartbeatIntervalMs);
+    // Chỉ được giãn khi CHÍNH APP thấy kênh MQTT khoẻ VÀ server cho phép
+    // (serverBeatHintMs). Không có nguồn sức khoẻ hoặc chưa có hint → giữ nhịp
+    // cũ y hệt trước đây; đây là lý do bật/tắt rollout không cần OTA lại.
+    const health = (() => {
+      try {
+        return this.options.mqttHealth?.() ?? null;
+      } catch {
+        return null;
+      }
+    })();
+    const adaptive = nextBeatDelayMs({
+      health,
+      now: Date.now(),
+      serverHintMs: this.serverBeatHintMs,
+      // Đang chạy lệnh / đang mở kênh điều khiển = có người chờ kết quả.
+      busy: this.executing || this.controlChannel !== null,
+    });
+    // `adaptive` chỉ vượt `base` khi ĐỦ điều kiện giãn; mọi ca còn lại nó bằng
+    // 12s nên kết quả rơi về đúng hành vi cũ.
+    return Math.max(base, adaptive);
+  }
+
   private schedule(delayMs: number) {
     if (!this.running || !this.foreground) return;
     if (this.timer) clearTimeout(this.timer);
@@ -215,7 +381,7 @@ export class DeviceAgent {
         if (!this.registered) return; // register() đã schedule retry
       }
       await this.heartbeat();
-      this.schedule(this.heartbeatIntervalMs);
+      this.schedule(this.nextBeatDelay());
     } finally {
       this.beatInFlight = false;
     }
@@ -243,6 +409,24 @@ export class DeviceAgent {
     }
   }
 
+  /**
+   * Lọc metrics cho heartbeat: chỉ trả (và ghi nhớ) khi vượt ngưỡng
+   * (metricsCrossedThreshold) hoặc đã quá METRICS_BASELINE_MS kể từ lần gửi.
+   * Trả undefined = nhịp này không kèm metrics.
+   */
+  private selectMetricsForHeartbeat(
+    metrics: Record<string, number | string> | undefined,
+  ): Record<string, number | string> | undefined {
+    if (!metrics) return undefined;
+    const now = Date.now();
+    const crossed = metricsCrossedThreshold(this.lastSentMetrics, metrics);
+    const baselineDue = now - this.lastMetricsSentAt >= METRICS_BASELINE_MS;
+    if (!crossed && !baselineDue) return undefined;
+    this.lastSentMetrics = metrics;
+    this.lastMetricsSentAt = now;
+    return metrics;
+  }
+
   private async heartbeat() {
     const snapshot = this.options.engine.getSnapshot();
     let metrics: Record<string, number | string> | undefined;
@@ -251,7 +435,20 @@ export class DeviceAgent {
     } catch {
       metrics = undefined;
     }
-    let result: { controlSession: DeviceControlSessionGrant | null };
+    // Chỉ đính metrics khi vượt ngưỡng đáng báo hoặc tới mốc chẩn đoán nền —
+    // xem METRICS_BASELINE_MS. Bỏ metrics KHÔNG cản heartbeat: nhịp vẫn đi để
+    // giữ "online", chỉ là không kèm số liệu (server khỏi ghi lại metricsJson).
+    const metricsToSend = this.selectMetricsForHeartbeat(metrics);
+    let extras: DeviceHeartbeatExtras = {};
+    try {
+      extras = this.options.heartbeatExtras?.() ?? {};
+    } catch {
+      extras = {};
+    }
+    let result: {
+      controlSession: DeviceControlSessionGrant | null;
+      beatIntervalMs?: number;
+    };
     try {
       result = await this.options.transport.heartbeat({
         ...this.options.bootstrapInput,
@@ -260,7 +457,14 @@ export class DeviceAgent {
         ...(this.options.deviceInfo?.appVersion
           ? { appVersion: this.options.deviceInfo.appVersion }
           : {}),
-        ...(metrics ? { metrics } : {}),
+        ...(metricsToSend ? { metrics: metricsToSend } : {}),
+        ...(extras.recentExits && extras.recentExits.length > 0
+          ? { recentExits: extras.recentExits }
+          : {}),
+        ...(extras.powerState !== undefined ? { powerState: extras.powerState } : {}),
+        // Chỉ gửi khi TRUE. Server đọc doc tỉ số mỗi nhịp có cờ này, nên gửi
+        // `false` cũng vô hại nhưng phí một field trên mọi beat của mọi máy.
+        ...(extras.wantScore ? { wantScore: true } : {}),
       });
     } catch {
       // Lỗi liên tiếp (mạng, hoặc server đã xoá device) → thử re-register.
@@ -273,6 +477,11 @@ export class DeviceAgent {
       return;
     }
     this.heartbeatFailures = 0;
+    // Server nói nhịp kế; số lạ/thiếu thì quên đi và giữ nhịp nhanh.
+    this.serverBeatHintMs =
+      typeof result.beatIntervalMs === "number" && result.beatIntervalMs > 0
+        ? result.beatIntervalMs
+        : undefined;
     if (result.controlSession && !this.controlChannel) {
       this.openControlChannel(result.controlSession);
     }
@@ -374,6 +583,12 @@ export class DeviceAgent {
           sessionId ?? undefined,
         );
         if (sessionId) this.options.onRemoteSessionStarted?.(sessionId);
+      } else if (command.type === "publish_livestream") {
+        await this.runPublish();
+        await this.safeAck(channel, grant, command.id, "completed");
+      } else if (command.type === "unpublish_livestream") {
+        await this.runUnpublish();
+        await this.safeAck(channel, grant, command.id, "completed");
       } else {
         await this.runStopLivestream();
         await this.safeAck(channel, grant, command.id, "completed");
@@ -399,13 +614,19 @@ export class DeviceAgent {
       await engine.prepare();
     }
     const remote = this.options.remoteStart;
+    const courtRef = command.payload.courtRef?.trim();
     await engine.start(
       {
         externalSessionId: `remote-${command.id}`,
         title: command.payload.title?.trim() || remote.defaultTitle || "Livestream",
         visibility: command.payload.visibility ?? remote.visibility ?? "public",
         consentVersion: remote.consentVersion,
-        metadata: { ...remote.metadata, deviceCommandId: command.id },
+        metadata: {
+          ...remote.metadata,
+          deviceCommandId: command.id,
+          // courtRef trong metadata → server đậu phiên standby vào sân
+          ...(courtRef ? { courtRef } : {}),
+        },
         standby: true,
       },
       { autoPublish: false },
@@ -419,6 +640,38 @@ export class DeviceAgent {
     }
   }
 
+  /**
+   * standby → live theo lệnh dashboard. startPublishing() NUỐT lỗi (recordError
+   * vào snapshot thay vì throw) nên phải kiểm state sau khi gọi — không kiểm là
+   * lệnh được ack "completed" dù thiết bị chưa hề phát.
+   */
+  private async runPublish() {
+    const engine = this.options.engine;
+    const state = engine.getSnapshot().state;
+    if (state === "live") return; // đã phát — lệnh lặp coi như xong
+    if (state !== "standby") {
+      throw new Error(`Thiết bị không ở chế độ chờ (trạng thái ${state})`);
+    }
+    await engine.startPublishing();
+    if (engine.getSnapshot().state !== "live") {
+      const message = engine.getSnapshot().error?.message;
+      throw new Error(message ? `Không phát được: ${message}` : "Không phát được");
+    }
+  }
+
+  private async runUnpublish() {
+    const engine = this.options.engine;
+    const state = engine.getSnapshot().state;
+    if (state === "standby") return; // đã ở chế độ chờ
+    if (state !== "live") {
+      throw new Error(`Thiết bị không đang phát (trạng thái ${state})`);
+    }
+    await engine.stopPublishing();
+    if (engine.getSnapshot().state !== "standby") {
+      throw new Error("Không dừng phát được");
+    }
+  }
+
   private async safeAck(
     channel: DeviceControlChannel,
     grant: DeviceControlSessionGrant,

package/src/device-agent/beat-policy.ts

@@ -0,0 +1,46 @@
+/**
+ * Nhịp heartbeat thích ứng — bản CHÉP của luật trong
+ * `packages/shared/src/realtime.ts`.
+ *
+ * Vì sao chép chứ không import: gói expo-sdk cố ý KHÔNG phụ thuộc
+ * `@pickleball/shared` (guard `scripts/verify-pack.mjs` chặn), để app đối tác
+ * cài SDK không phải kéo theo cả gói dùng chung của backend. Đổi luật ở đây thì
+ * phải đổi cả hai nơi — bộ test hai bên dùng CÙNG bảng giá trị để phát hiện lệch.
+ */
+
+export const BEAT_SLOW_MS = 60_000;
+export const BEAT_FAST_MS = 12_000;
+export const MQTT_HEALTHY_SILENCE_MS = 45_000;
+export const MQTT_HEALTHY_HOLD_MS = 120_000;
+
+export interface MqttBeatHealth {
+  connected: boolean;
+  subscribed: boolean;
+  lastInboundAt: number;
+  healthySince: number;
+}
+
+/** Đủ CẢ BỐN vế mới được coi là kênh khoẻ. */
+export function mqttBeatHealthy(h: MqttBeatHealth, now: number): boolean {
+  if (!h.connected || !h.subscribed) return false;
+  if (h.lastInboundAt <= 0 || now - h.lastInboundAt >= MQTT_HEALTHY_SILENCE_MS) return false;
+  if (h.healthySince <= 0 || now - h.healthySince < MQTT_HEALTHY_HOLD_MS) return false;
+  return true;
+}
+
+/**
+ * Nhịp kế tiếp = min(luật nội bộ, hint của server), và THIẾU hint thì mặc định
+ * nhanh. Nhờ vậy máy chưa nhận được hint (server cũ, hoặc beat lỗi) không bao
+ * giờ tự ý giãn nhịp, còn tắt rollout chỉ là đổi một biến env phía server.
+ */
+export function nextBeatDelayMs(input: {
+  health: MqttBeatHealth | null;
+  now: number;
+  serverHintMs?: number;
+  busy?: boolean;
+}): number {
+  const hint = input.serverHintMs ?? BEAT_FAST_MS;
+  if (input.busy || !input.health) return BEAT_FAST_MS;
+  const local = mqttBeatHealthy(input.health, input.now) ? BEAT_SLOW_MS : BEAT_FAST_MS;
+  return Math.min(local, hint);
+}

package/src/device-agent/component.tsx

@@ -1,10 +1,12 @@
 import { useEffect, useRef } from "react";
+import type { MqttBeatHealth } from "./beat-policy";
 import { useLivestreamHost } from "../provider";
 import {
   DeviceAgent,
   type DeviceAgentDeviceInfo,
   type DeviceAgentTransport,
   type DeviceControlChannel,
+  type DeviceHeartbeatExtras,
   type RemoteStartConfig,
 } from "./agent";
 
@@ -20,6 +22,13 @@ export interface PickleballDeviceAgentProps {
   deviceInfo?: DeviceAgentDeviceInfo;
   onRemoteSessionStarted?: (sessionId: string) => void;
   createControlChannel?: (convexUrl: string) => DeviceControlChannel;
+  /** Field bổ sung cho heartbeat (VD recentExits) — đọc qua ref nên đổi hàm không dựng lại agent. */
+  heartbeatExtras?: () => DeviceHeartbeatExtras | undefined;
+  /**
+   * Sức khoẻ kênh MQTT của app — nguồn để agent giãn nhịp beat khi kênh khoẻ
+   * VÀ server bật rollout. Bỏ trống = agent giữ nhịp cũ.
+   */
+  mqttHealth?: () => MqttBeatHealth | null;
 }
 
 export function PickleballDeviceAgent(props: PickleballDeviceAgentProps) {
@@ -40,6 +49,8 @@ export function PickleballDeviceAgent(props: PickleballDeviceAgentProps) {
       createControlChannel: propsRef.current.createControlChannel,
       onRemoteSessionStarted: (sessionId) =>
         propsRef.current.onRemoteSessionStarted?.(sessionId),
+      heartbeatExtras: () => propsRef.current.heartbeatExtras?.(),
+      mqttHealth: () => propsRef.current.mqttHealth?.() ?? null,
     });
     agent.start();
     return () => agent.stop();

package/src/device-agent/convex-beat-transport.ts

@@ -0,0 +1,140 @@
+import type { BootstrapInput } from "../contracts";
+import type {
+  DeviceAgentDeviceInfo,
+  DeviceAgentTransport,
+  DeviceControlSessionGrant,
+  DeviceHeartbeatBody,
+} from "./agent";
+import type { ConvexDeviceRealtime } from "./convex-command-subscription";
+
+/**
+ * Bọc transport HTTP để heartbeat đi đường WEBSOCKET (mutation deviceApp.beat,
+ * 1 function call) thay vì POST /devices/heartbeat (httpAction→runMutation,
+ * 2 call). Ở 1.000 máy nhịp 12s, đó là 216M call/tháng so với 108M — một nửa
+ * hoá đơn chỉ bằng cách đổi đường vận chuyển, không đổi ngữ nghĩa.
+ *
+ * register/pairing GIỮ HTTP: đó là lúc máy CHƯA có deviceToken (chưa auth WS
+ * được), và là việc hiếm — không đáng tối ưu.
+ *
+ * Luật fallback: mọi lỗi WS (mất mạng, token hỏng, server chưa deploy beat...)
+ * → rơi về HTTP NGAY trong nhịp đó, và nghỉ thử WS một quãng để mỗi beat
+ * không phải trả thêm một lần timeout khi WS đang hỏng kéo dài. Máy bản này chạy
+ * với server cũ chưa có `deviceApp.beat` vẫn sống bình thường qua HTTP.
+ */
+
+/** WS hỏng thì nghỉ thử ngần này rồi mới thử lại — tránh mỗi beat +10s timeout. */
+const WS_BEAT_RETRY_MS = 60_000;
+/**
+ * Trần chờ một lượt beat WS. PHẢI có: ConvexClient.mutation KHÔNG tự timeout —
+ * mất mạng là nó xếp hàng chờ reconnect vô hạn, thiếu trần này thì heartbeat
+ * treo và không bao giờ rơi về HTTP. Mutation xếp hàng có thể vẫn chạy SAU khi
+ * mạng về → beat đúp — vô hại, heartbeat lặp là ngữ nghĩa bình thường.
+ */
+const WS_BEAT_TIMEOUT_MS = 10_000;
+
+export interface ConvexBeatOptions {
+  /** deviceToken hiện tại (đọc mỗi nhịp — token có thể vừa được cấp/đổi). */
+  getDeviceToken: () => string | null | undefined;
+  /**
+   * Cùng hook với createHttpDeviceAgentTransport.onData: đường WS phải đổ
+   * envelope y hệt để handleTransportData (claim/pairing/assignedCourt/
+   * activeSession/preview) không phân biệt beat đến từ đường nào.
+   */
+  onData?: (endpoint: "heartbeat", data: Record<string, unknown>) => void;
+  timeoutMs?: number;
+  /** Test hook. */
+  now?: () => number;
+}
+
+export function withConvexBeat(
+  base: DeviceAgentTransport,
+  realtime: ConvexDeviceRealtime,
+  options: ConvexBeatOptions,
+): DeviceAgentTransport {
+  const now = options.now ?? Date.now;
+  const timeoutMs = options.timeoutMs ?? WS_BEAT_TIMEOUT_MS;
+  let wsBrokenUntil = 0;
+
+  return {
+    register(input: BootstrapInput & DeviceAgentDeviceInfo) {
+      return base.register(input);
+    },
+    async heartbeat(input: BootstrapInput & DeviceHeartbeatBody) {
+      const deviceToken = options.getDeviceToken();
+      if (!deviceToken || now() < wsBrokenUntil) {
+        return base.heartbeat(input);
+      }
+      try {
+        const data = await withTimeout(
+          realtime.beat({
+            deviceToken,
+            // Server tra máy theo token — bootstrapInput (installationId…) chỉ
+            // đường HTTP cần. Chỉ gửi đúng phần mutation beat nhận.
+            agentState: input.agentState,
+            currentSessionId: input.currentSessionId,
+            ...(input.appVersion !== undefined ? { appVersion: input.appVersion } : {}),
+            ...(input.metrics !== undefined ? { metrics: input.metrics } : {}),
+            ...(input.recentExits !== undefined && input.recentExits.length > 0
+              ? { recentExits: input.recentExits }
+              : {}),
+            ...(input.powerState !== undefined ? { powerState: input.powerState } : {}),
+          }),
+          timeoutMs,
+        );
+        options.onData?.("heartbeat", data);
+        // Cùng lý do với http-transport: transport là nơi DUY NHẤT dữ liệu beat
+        // đi qua, không chuyển tiếp ở đây là agent vĩnh viễn không thấy hint.
+        return {
+          controlSession: parseControlSession(data.controlSession),
+          ...(typeof data.beatIntervalMs === "number" &&
+          Number.isFinite(data.beatIntervalMs)
+            ? { beatIntervalMs: data.beatIntervalMs }
+            : {}),
+        };
+      } catch {
+        // Không phân loại lỗi: nguyên nhân nào thì hành động cũng là dùng HTTP
+        // nhịp này và nghỉ thử WS một quãng.
+        wsBrokenUntil = now() + WS_BEAT_RETRY_MS;
+        return base.heartbeat(input);
+      }
+    },
+  };
+}
+
+/** Cùng luật parse với đường HTTP — grant lệch dạng coi như beat hỏng (throw). */
+function parseControlSession(grant: unknown): DeviceControlSessionGrant | null {
+  if (grant === null || grant === undefined) return null;
+  if (
+    grant === null ||
+    typeof grant !== "object" ||
+    typeof (grant as Record<string, unknown>).id !== "string" ||
+    typeof (grant as Record<string, unknown>).token !== "string" ||
+    typeof (grant as Record<string, unknown>).convexUrl !== "string" ||
+    (grant as Record<string, unknown>).convexUrl === ""
+  ) {
+    throw new Error("Invalid controlSession in beat response");
+  }
+  const record = grant as Record<string, unknown>;
+  return {
+    id: record.id as string,
+    token: record.token as string,
+    convexUrl: record.convexUrl as string,
+  };
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error("beat timeout")), ms);
+    (timer as unknown as { unref?: () => void }).unref?.();
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}