@firstperson/firstperson 2026.1.33 → 2026.1.34

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2026.1.34
+
+- Improve relay connection stability for production use:
+  - Add client-side heartbeat ping every 30s to keep connections alive and detect dead connections faster
+  - Reset reconnect backoff counter after 60s of stable connection
+  - Remove max reconnect attempt limit - gateway will always keep trying to reconnect
+
 ## 2026.1.33
 
 - Fix npm package name to `@firstperson/firstperson` (must match plugin ID)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstperson/firstperson",
-  "version": "2026.1.33",
+  "version": "2026.1.34",
   "type": "module",
   "description": "OpenClaw channel plugin for the First Person iOS app",
   "main": "index.ts",

package/src/relay-client.ts

@@ -142,9 +142,23 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
 
   let ws: WebSocket | null = null;
   let reconnectAttempts = 0;
-  const maxReconnectAttempts = 10;
   const baseReconnectDelay = 1000;
 
+  // Timers for heartbeat and stability tracking
+  let pingInterval: ReturnType<typeof setInterval> | null = null;
+  let stabilityTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const clearTimers = () => {
+    if (pingInterval) {
+      clearInterval(pingInterval);
+      pingInterval = null;
+    }
+    if (stabilityTimer) {
+      clearTimeout(stabilityTimer);
+      stabilityTimer = null;
+    }
+  };
+
   const connect = () => {
     if (abortSignal.aborted) {
       log("info", "[relay-client] connect() called but abortSignal already aborted");
@@ -156,8 +170,27 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
 
     ws.on("open", () => {
       log("info", `[relay-client] WebSocket opened, readyState: ${ws?.readyState}`);
-      reconnectAttempts = 0;
       activeWs = ws; // Store as active connection for sending
+
+      // Clear any existing timers from previous connection attempts
+      clearTimers();
+
+      // Start client-side heartbeat: send ping every 30s to keep connection alive
+      pingInterval = setInterval(() => {
+        if (ws?.readyState === WebSocket.OPEN) {
+          log("info", "[relay-client] Sending heartbeat ping");
+          ws.send(JSON.stringify({ type: "ping" }));
+        }
+      }, 30000);
+
+      // Reset reconnect counter after connection is stable for 60s
+      stabilityTimer = setTimeout(() => {
+        if (ws?.readyState === WebSocket.OPEN && reconnectAttempts > 0) {
+          log("info", `[relay-client] Connection stable for 60s, resetting reconnect counter (was ${reconnectAttempts})`);
+          reconnectAttempts = 0;
+        }
+      }, 60000);
+
       onConnected();
     });
 
@@ -172,6 +205,11 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
           return;
         }
 
+        if (msg.type === "pong") {
+          // Server acknowledged our heartbeat ping - connection is healthy
+          return;
+        }
+
         // Handle send acknowledgments for replies sent through this connection
         if ((msg.type === "message_sent" || msg.type === "ack") && msg.messageId) {
           const pending = pendingReplies.get(msg.messageId);
@@ -213,6 +251,9 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
       );
       log("info", `[relay-client] abortSignal.aborted: ${abortSignal.aborted}`);
 
+      // Clear timers on disconnect
+      clearTimers();
+
       // Clear active connection and reject pending replies
       if (activeWs === ws) {
         activeWs = null;
@@ -228,19 +269,15 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
         return;
       }
 
+      // Always reconnect - never give up (exponential backoff capped at 30s)
       reconnectAttempts++;
-      if (reconnectAttempts <= maxReconnectAttempts) {
-        const delay = Math.min(baseReconnectDelay * Math.pow(2, reconnectAttempts - 1), 30000);
-        log(
-          "info",
-          `[relay-client] Reconnecting in ${delay}ms (attempt ${reconnectAttempts} of ${maxReconnectAttempts})`
-        );
-        setTimeout(connect, delay);
-        onDisconnected(new Error(`Connection closed, reconnecting in ${delay}ms...`));
-      } else {
-        log("warn", "[relay-client] Max reconnection attempts reached");
-        onDisconnected(new Error("Max reconnection attempts reached"));
-      }
+      const delay = Math.min(baseReconnectDelay * Math.pow(2, reconnectAttempts - 1), 30000);
+      log(
+        "info",
+        `[relay-client] Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`
+      );
+      setTimeout(connect, delay);
+      onDisconnected(new Error(`Connection closed, reconnecting in ${delay}ms...`));
     });
 
     ws.on("error", (err) => {
@@ -252,6 +289,7 @@ export async function startRelayConnection(params: RelayConnectionParams): Promi
   // Handle abort signal
   abortSignal.addEventListener("abort", () => {
     log("info", "[relay-client] Abort signal received, closing WebSocket");
+    clearTimers();
     if (activeWs === ws) {
       activeWs = null;
       activeLogger = null;