@pickleball/expo-sdk 0.1.1 → 1.0.0

package/src/device-agent/agent.ts

@@ -0,0 +1,696 @@
+import { nextBeatDelayMs, type MqttBeatHealth } from "./beat-policy";
+import type { BootstrapInput } from "../contracts";
+import type { DeviceMetricsSample, LivestreamEngine } from "../engine";
+import { normalizeError } from "../errors";
+
+/**
+ * DeviceAgent — đăng ký thiết bị với backend khi app mở và giữ heartbeat
+ * presence (12s/lần khi foreground) qua proxy. Khi dashboard yêu cầu "Kết nối",
+ * heartbeat trả về connect-token → agent mở kênh điều khiển realtime (Convex
+ * websocket) để nhận lệnh start/stop livestream tức thì. Publish/unpublish sau
+ * khi vào standby vẫn đi đường LiveKit data channel sẵn có của engine.
+ */
+
+export interface DeviceAgentDeviceInfo {
+  appVersion?: string;
+  deviceName?: string;
+  deviceModel?: string;
+  osVersion?: string;
+}
+
+export interface DeviceCommand {
+  id: string;
+  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;
+}
+
+export interface DeviceControlSessionGrant {
+  id: string;
+  token: string;
+  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;
+    /**
+     * 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). */
+export interface DeviceControlChannel {
+  attach(controlSessionId: string, token: string): Promise<void>;
+  /** Subscribe lệnh pending — callback gọi lại mỗi khi danh sách đổi. */
+  onCommands(
+    controlSessionId: string,
+    token: string,
+    callback: (commands: DeviceCommand[]) => void,
+  ): () => void;
+  /** Subscribe trạng thái kênh — "ended"/"expired" thì agent tự đóng. */
+  onState(
+    controlSessionId: string,
+    token: string,
+    callback: (state: { status: string }) => void,
+  ): () => void;
+  ack(input: {
+    controlSessionId: string;
+    token: string;
+    commandId: string;
+    status: "acked" | "completed" | "failed";
+    errorMessage?: string;
+    resultSessionId?: string;
+  }): Promise<void>;
+  close(): void;
+}
+
+export interface RemoteStartConfig {
+  consentVersion: string;
+  /** Tiêu đề mặc định khi dashboard không gửi title. */
+  defaultTitle?: string;
+  visibility?: "public" | "private";
+  metadata?: Record<string, string>;
+}
+
+type AppStateListener = (state: "active" | "background" | "inactive") => void;
+
+export interface DeviceAgentOptions {
+  engine: LivestreamEngine;
+  bootstrapInput: BootstrapInput;
+  transport: DeviceAgentTransport;
+  remoteStart: RemoteStartConfig;
+  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. */
+  subscribeAppState?: (listener: AppStateListener) => () => void;
+}
+
+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",
+  "ramTotalMb",
+  "storageFreeGb",
+  "batteryPct",
+  "batteryTempC",
+  "thermal",
+  "netType",
+  "linkMbps",
+  "rssi",
+  "connQuality",
+  "signalPct",
+  "localIp",
+] as const;
+
+function defaultSubscribeAppState(listener: AppStateListener): () => void {
+  const { AppState } = require("react-native") as typeof import("react-native");
+  const subscription = AppState.addEventListener("change", (state) => {
+    listener(
+      state === "active" ? "active" : state === "background" ? "background" : "inactive",
+    );
+  });
+  return () => subscription.remove();
+}
+
+function defaultCreateControlChannel(convexUrl: string): DeviceControlChannel {
+  const { createConvexControlChannel } =
+    require("./convex-control-channel") as typeof import("./convex-control-channel");
+  return createConvexControlChannel(convexUrl);
+}
+
+function pickMetrics(
+  sample: DeviceMetricsSample | null,
+): Record<string, number | string> | undefined {
+  if (!sample) return undefined;
+  const metrics: Record<string, number | string> = {};
+  for (const field of METRIC_FIELDS) {
+    const value = (sample as Record<string, unknown>)[field];
+    if (typeof value === "number" && Number.isFinite(value)) metrics[field] = value;
+    else if (typeof value === "string" && value.trim() !== "") metrics[field] = value;
+  }
+  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> = [];
+  private executing = false;
+  private readonly handledCommandIds = new Set<string>();
+
+  constructor(options: DeviceAgentOptions) {
+    this.options = options;
+  }
+
+  start() {
+    if (this.running) return;
+    this.running = true;
+    this.unsubscribeAppState = (
+      this.options.subscribeAppState ?? defaultSubscribeAppState
+    )((state) => this.handleAppState(state));
+    this.schedule(0);
+  }
+
+  stop() {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.unsubscribeAppState?.();
+    this.unsubscribeAppState = null;
+    this.closeControlChannel();
+  }
+
+  private handleAppState(state: "active" | "background" | "inactive") {
+    const wasForeground = this.foreground;
+    this.foreground = state === "active";
+    if (!this.running) return;
+    if (this.foreground && !wasForeground) {
+      // Về foreground: beat ngay để dashboard thấy online lại nhanh
+      this.schedule(0);
+    }
+    if (!this.foreground) {
+      if (this.timer) clearTimeout(this.timer);
+      this.timer = null;
+      // App nền không quay được — đóng kênh, server sẽ end control-session
+      this.closeControlChannel();
+    }
+  }
+
+  /**
+   * Đ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);
+    this.timer = setTimeout(() => {
+      void this.beat();
+    }, delayMs);
+  }
+
+  private async beat() {
+    if (!this.running || !this.foreground || this.beatInFlight) return;
+    this.beatInFlight = true;
+    try {
+      if (!this.registered) {
+        await this.register();
+        if (!this.registered) return; // register() đã schedule retry
+      }
+      await this.heartbeat();
+      this.schedule(this.nextBeatDelay());
+    } finally {
+      this.beatInFlight = false;
+    }
+  }
+
+  private async register() {
+    try {
+      const result = await this.options.transport.register({
+        ...this.options.bootstrapInput,
+        ...this.options.deviceInfo,
+      });
+      if (result.heartbeatIntervalMs > 0) {
+        this.heartbeatIntervalMs = result.heartbeatIntervalMs;
+      }
+      this.registered = true;
+      this.registerAttempt = 0;
+    } catch {
+      // Mạng lỗi/proxy chưa sẵn sàng — backoff rồi thử lại
+      const delay = Math.min(
+        REGISTER_RETRY_BASE_MS * 2 ** this.registerAttempt,
+        REGISTER_RETRY_MAX_MS,
+      );
+      this.registerAttempt += 1;
+      this.schedule(delay);
+    }
+  }
+
+  /**
+   * 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;
+    try {
+      metrics = pickMetrics((await this.options.deviceMetrics?.()) ?? null);
+    } catch {
+      metrics = undefined;
+    }
+    // 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,
+        agentState: snapshot.state,
+        currentSessionId: snapshot.sessionId,
+        ...(this.options.deviceInfo?.appVersion
+          ? { appVersion: this.options.deviceInfo.appVersion }
+          : {}),
+        ...(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.
+      // Register là upsert idempotent nên gọi lại vô hại.
+      this.heartbeatFailures += 1;
+      if (this.heartbeatFailures >= 3) {
+        this.registered = false;
+        this.heartbeatFailures = 0;
+      }
+      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);
+    }
+  }
+
+  private openControlChannel(grant: DeviceControlSessionGrant) {
+    let channel: DeviceControlChannel;
+    try {
+      channel = (this.options.createControlChannel ?? defaultCreateControlChannel)(
+        grant.convexUrl,
+      );
+    } catch {
+      return;
+    }
+    this.controlChannel = channel;
+    this.controlSessionId = grant.id;
+    void channel
+      .attach(grant.id, grant.token)
+      .then(() => {
+        if (this.controlChannel !== channel) return;
+        this.controlUnsubscribers.push(
+          channel.onCommands(grant.id, grant.token, (commands) => {
+            void this.executeCommands(channel, grant, commands);
+          }),
+          channel.onState(grant.id, grant.token, (state) => {
+            if (state.status === "ended" || state.status === "expired") {
+              this.closeControlChannel();
+            }
+          }),
+        );
+      })
+      .catch(() => {
+        if (this.controlChannel === channel) this.closeControlChannel();
+      });
+  }
+
+  private closeControlChannel() {
+    for (const unsubscribe of this.controlUnsubscribers) {
+      try {
+        unsubscribe();
+      } catch {
+        /* kênh đã đóng */
+      }
+    }
+    this.controlUnsubscribers = [];
+    try {
+      this.controlChannel?.close();
+    } catch {
+      /* kênh đã đóng */
+    }
+    this.controlChannel = null;
+    this.controlSessionId = null;
+    this.handledCommandIds.clear();
+  }
+
+  private async executeCommands(
+    channel: DeviceControlChannel,
+    grant: DeviceControlSessionGrant,
+    commands: DeviceCommand[],
+  ) {
+    for (const command of commands) {
+      if (this.controlChannel !== channel) return;
+      if (this.handledCommandIds.has(command.id)) continue;
+      this.handledCommandIds.add(command.id);
+      if (this.executing) {
+        // Single-flight: server cũng dedupe, nhưng phòng lệnh dồn trong 1 batch
+        await this.safeAck(channel, grant, command.id, "failed", "Thiết bị đang bận");
+        continue;
+      }
+      this.executing = true;
+      try {
+        await this.executeCommand(channel, grant, command);
+      } finally {
+        this.executing = false;
+      }
+    }
+  }
+
+  private async executeCommand(
+    channel: DeviceControlChannel,
+    grant: DeviceControlSessionGrant,
+    command: DeviceCommand,
+  ) {
+    if (command.expiresAt <= Date.now()) {
+      await this.safeAck(channel, grant, command.id, "failed", "Lệnh đã hết hạn");
+      return;
+    }
+    await this.safeAck(channel, grant, command.id, "acked");
+    try {
+      if (command.type === "start_livestream") {
+        await this.runStartLivestream(command);
+        const sessionId = this.options.engine.getSnapshot().sessionId;
+        await this.safeAck(
+          channel,
+          grant,
+          command.id,
+          "completed",
+          undefined,
+          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");
+      }
+    } catch (error) {
+      await this.safeAck(
+        channel,
+        grant,
+        command.id,
+        "failed",
+        normalizeError(error).message,
+      );
+    }
+  }
+
+  private async runStartLivestream(command: DeviceCommand) {
+    const engine = this.options.engine;
+    const state = engine.getSnapshot().state;
+    if (state !== "idle" && state !== "ended" && state !== "preview") {
+      throw new Error(`Thiết bị không sẵn sàng (trạng thái ${state})`);
+    }
+    if (state !== "preview") {
+      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,
+          // courtRef trong metadata → server đậu phiên standby vào sân
+          ...(courtRef ? { courtRef } : {}),
+        },
+        standby: true,
+      },
+      { autoPublish: false },
+    );
+  }
+
+  private async runStopLivestream() {
+    const engine = this.options.engine;
+    if (engine.getSnapshot().sessionId) {
+      await engine.stop("user");
+    }
+  }
+
+  /**
+   * 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,
+    commandId: string,
+    status: "acked" | "completed" | "failed",
+    errorMessage?: string,
+    resultSessionId?: string,
+  ) {
+    try {
+      await channel.ack({
+        controlSessionId: grant.id,
+        token: grant.token,
+        commandId,
+        status,
+        ...(errorMessage !== undefined ? { errorMessage } : {}),
+        ...(resultSessionId !== undefined ? { resultSessionId } : {}),
+      });
+    } catch {
+      /* mất kênh giữa chừng — server cron sẽ expire lệnh */
+    }
+  }
+}