@mentra/engine 0.1.0-beta.0

package/src/services/otaInstallPolicy.ts

@@ -0,0 +1,106 @@
+/** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */
+import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+/**
+ * First glasses `build_number` (ASG `versionCode`) that uses `progress.tsx` with unified
+ * `ota_status` session UI. Strictly lower builds use `/ota/progress-legacy` (routed from
+ * `check-for-updates.tsx` before navigation), and get the LEGACY_* padded policy below
+ * in the unified OtaInstallCoordinator (WP 8C). Change only here.
+ */
+export const MINIMUM_OTA_STATUS_BUILD = 37
+
+export const MAX_RETRIES = 3
+export const RETRY_INTERVAL_MS = 5000
+/** APK/BES and general install when progress events are expected */
+export const PROGRESS_TIMEOUT_MS = 120_000
+/** Fail if still at 0% in starting/downloading */
+export const DOWNLOAD_STUCK_TIMEOUT_MS = 70_000
+/** MTK system install often goes quiet for long periods */
+export const MTK_INSTALL_TIMEOUT_MS = 300_000
+/** Whole multi-step session cap */
+export const GLOBAL_OTA_TIMEOUT_MS = 20 * 60 * 1000
+/** After APK reboot, ASG OTA service needs time before next ota_start */
+export const POST_APK_OTA_START_DELAY_MS = 6000
+/** BLE keepalive during OTA */
+export const PING_INTERVAL_MS = 10_000
+/**
+ * If we sent ota_query_status (e.g. on reconnect) and the glasses haven't
+ * replied with an ota_status by then, fall back to ota_start. This recovers
+ * from the case where the glasses process restarted between mount and
+ * reconnect — the session is gone, ota_query_status returns nothing, and
+ * the user would otherwise sit on the spinner forever.
+ */
+export const QUERY_REPLY_TIMEOUT_MS = 6000
+/** 15s lockout on the Continue button after a BES restart, to prevent an accidental tap. */
+export const BES_CONTINUE_LOCKOUT_MS = 15_000
+
+// --- Legacy old-build (< MINIMUM_OTA_STATUS_BUILD) OTA policy (WP 8C) ---
+//
+// Ported verbatim from mobile/src/app/ota/progress-legacy.tsx, which padded EVERY
+// watchdog/timer by +20s for old ASG builds ("Legacy OTA: +20s on every watchdog /
+// timer duration"). Old builds respond slower on every path, so where the legacy
+// screen used a longer duration the coordinator applies the longer value whenever
+// the session is legacy-shaped (see isLegacyShapedOtaStatus / the coordinator's
+// session-shape check). Builds >= 37 keep the unpadded values above.
+
+/** The uniform pad progress-legacy.tsx added to every duration for old builds. */
+export const LEGACY_EXTRA_TIMEOUT_MS = 20_000
+export const LEGACY_RETRY_INTERVAL_MS = RETRY_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_PROGRESS_TIMEOUT_MS = PROGRESS_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS = DOWNLOAD_STUCK_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_INSTALL_TIMEOUT_MS = MTK_INSTALL_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_GLOBAL_OTA_TIMEOUT_MS = GLOBAL_OTA_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_PING_INTERVAL_MS = PING_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_BES_CONTINUE_LOCKOUT_MS = BES_CONTINUE_LOCKOUT_MS + LEGACY_EXTRA_TIMEOUT_MS
+/**
+ * After a legacy apk `install FINISHED` observed in-flight, the legacy screen held the
+ * completed state for 12s (+20s pad) so the ASG process restart settles (and fresh
+ * version_info lands) before the user can continue.
+ */
+export const LEGACY_APK_COMPLETION_SETTLE_MS = 12_000 + LEGACY_EXTRA_TIMEOUT_MS
+/**
+ * Legacy MTK install stall simulation (display-only): the MTK system install typically
+ * stalls around 49-50%. After LEGACY_MTK_STALL_DETECT_MS without a new event in the
+ * [45, 55) zone, the legacy screen simulated +1% every LEGACY_MTK_SIM_TICK_MS starting
+ * at max(stall+1, 51) and capped at 60%, purely to keep the user informed.
+ */
+export const LEGACY_MTK_STALL_DETECT_MS = 20_000 + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_SIM_TICK_MS = 15_000 + LEGACY_EXTRA_TIMEOUT_MS
+export const LEGACY_MTK_STALL_ZONE_MIN_PERCENT = 45
+export const LEGACY_MTK_STALL_ZONE_MAX_PERCENT = 55
+export const LEGACY_MTK_SIM_FLOOR_PERCENT = 51
+export const LEGACY_MTK_SIM_CAP_PERCENT = 60
+
+/**
+ * Legacy-shaped ota_status: old (< 37) ASG builds send `ota_progress`, which the SDK
+ * (Android MentraLive.kt / iOS MentraLive.swift) maps to a unified ota_status with
+ * sessionId "" and totalSteps 1, and FINISHED→"complete" regardless of phase. A real
+ * (>= 37) session always carries a sessionId; an "idle" reply also has sessionId "" but
+ * proves the glasses speak the unified protocol, so it is NOT legacy-shaped.
+ */
+export function isLegacyShapedOtaStatus(otaStatus: OtaStatus | null): boolean {
+  return !!otaStatus && otaStatus.sessionId === "" && otaStatus.status !== "idle"
+}
+
+/**
+ * Is the current install session legacy-shaped? Event shape wins when events exist
+ * (per the WP 8C rule: key off legacy-shaped inputs, not a build flag, where possible);
+ * before any event arrives only the glasses build number can tell.
+ */
+export function isLegacyShapedOtaSession(
+  otaStatus: OtaStatus | null,
+  otaProgress: OtaProgress | null,
+  buildNumber: string | null | undefined,
+): boolean {
+  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus)
+  if (otaProgress) return true
+  const build = Number.parseInt(buildNumber ?? "", 10)
+  return Number.isFinite(build) && build > 0 && build < MINIMUM_OTA_STATUS_BUILD
+}
+
+export const OtaProgressMessages = {
+  noAckResponse: "Unable to start update. Glasses did not respond.",
+  stalledOrStuck: "Update may have failed. Ensure glasses have internet access and try again.",
+  globalTimeout: "Update took too long. Please try again.",
+  sendOtaStartFailed: "Failed to communicate with glasses.",
+} as const

package/src/services/otaLegacyMapping.ts

@@ -0,0 +1,71 @@
+import type {OtaProgress, OtaProgressStatus, OtaStatus} from "@mentra/bluetooth-sdk/internal"
+
+/** Normalized ota_status fields (snake_case) after bridging Core/expo (snake or camel). */
+export type NormalizedOtaStatusEvent = {
+  session_id: string
+  total_steps: number
+  current_step: number
+  step_type: string
+  phase: "download" | "install"
+  step_percent: number
+  overall_percent: number
+  status: string
+  error_message?: string
+}
+
+/**
+ * Core may deliver ota_status with snake_case (Android) or camelCase (some bridge paths).
+ * Use this for Mantle and legacy otaProgress mapping.
+ */
+export function normalizeOtaStatusEvent(event: Record<string, unknown>): NormalizedOtaStatusEvent {
+  const e = event as Record<string, any>
+  const phase: "download" | "install" = e?.phase === "install" ? "install" : "download"
+  const err = e?.error_message ?? e?.errorMessage
+  return {
+    session_id: String(e?.session_id ?? e?.sessionId ?? ""),
+    total_steps: Number(e?.total_steps ?? e?.totalSteps ?? 0),
+    current_step: Number(e?.current_step ?? e?.currentStep ?? 0),
+    step_type: String(e?.step_type ?? e?.stepType ?? "apk"),
+    phase,
+    step_percent: Number(e?.step_percent ?? e?.stepPercent ?? 0),
+    overall_percent: Number(e?.overall_percent ?? e?.overallPercent ?? 0),
+    status: String(e?.status ?? "idle"),
+    error_message: err == null || err === "" ? undefined : String(err),
+  }
+}
+
+export function otaStatusFromNormalized(n: NormalizedOtaStatusEvent): OtaStatus {
+  return {
+    sessionId: n.session_id,
+    totalSteps: n.total_steps,
+    currentStep: n.current_step,
+    stepType: n.step_type as OtaStatus["stepType"],
+    phase: n.phase,
+    stepPercent: n.step_percent,
+    overallPercent: n.overall_percent,
+    status: n.status as OtaStatus["status"],
+    error: n.error_message,
+  }
+}
+
+/** Maps unified ota_status from Core into the legacy otaProgress store shape (progress-legacy, settings). */
+export function legacyOtaProgressFromOtaStatusEvent(
+  event: Record<string, unknown> | NormalizedOtaStatusEvent,
+): OtaProgress {
+  const n = normalizeOtaStatusEvent(event as Record<string, unknown>)
+  const raw = (n.overall_percent ?? n.step_percent ?? 0) as number
+  let st: OtaProgressStatus = "PROGRESS"
+  // Native K900 BES OTA (sr_adota) sends step_complete, not complete, on success — map for progress-legacy FINISHED.
+  if (n.status === "complete" || n.status === "step_complete") st = "FINISHED"
+  else if (n.status === "failed") st = "FAILED"
+  else if (n.status === "idle") st = "STARTED"
+  return {
+    stage: n.phase === "install" ? "install" : "download",
+    status: st,
+    progress: Math.round(raw),
+    bytesDownloaded: 0,
+    totalBytes: 0,
+    currentUpdate: n.step_type || "apk",
+    errorMessage: n.error_message,
+  }
+}

package/src/services/slimStreamStatus.ts

@@ -0,0 +1,28 @@
+import type {StreamStatusEvent} from "@mentra/bluetooth-sdk/internal"
+
+/** Fields forwarded to cloud / miniapps after the first resolvedConfig ack. */
+export function slimStreamStatusEvent(
+  event: StreamStatusEvent,
+  options: {includeResolvedConfig?: boolean} = {},
+): Record<string, unknown> {
+  const slim: Record<string, unknown> = {
+    type: "stream_status",
+    kind: event.kind,
+    status: event.status,
+  }
+  if (event.streamId) slim.streamId = event.streamId
+  const ts = event.timestamp
+  if (typeof ts === "number" && Number.isFinite(ts)) slim.timestamp = ts
+  if (options.includeResolvedConfig && event.resolvedConfig) {
+    slim.resolvedConfig = event.resolvedConfig
+  }
+  // Live telemetry passes straight through — unlike resolvedConfig it changes
+  // per event, and the signature dedupe upstream only suppresses identical
+  // payloads.
+  if (event.stats) slim.stats = event.stats
+  return slim
+}
+
+export function streamStatusSignature(payload: Record<string, unknown>): string {
+  return JSON.stringify(payload)
+}