@firstperson/firstperson 2026.1.33 → 2026.1.35

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.35",
   "type": "module",
   "description": "OpenClaw channel plugin for the First Person iOS app",
   "main": "index.ts",
@@ -19,7 +19,9 @@
     "ai-assistant"
   ],
   "openclaw": {
-    "extensions": ["./index.ts"],
+    "extensions": [
+      "./index.ts"
+    ],
     "channel": {
       "id": "firstperson",
       "label": "First Person",

package/src/channel.ts

@@ -294,7 +294,7 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
         lastError: null,
       });
 
-      const { startRelayConnection } = await import("./relay-client.js");
+      const { startRelayConnection, sendStatusUpdate } = await import("./relay-client.js");
 
       return startRelayConnection({
         relayUrl: account.relayUrl,
@@ -325,6 +325,9 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
         onMessage: async (message) => {
           log?.info(`[fp] 1. received: ${message.messageId} from ${message.deviceId}`);
 
+          // Track timing for status updates
+          const dispatchStartTime = Date.now();
+
           try {
             const globalRuntime = getFirstPersonRuntime();
             const channelApi = (globalRuntime as any).channel;
@@ -417,6 +420,13 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
 
               if (!route) {
                 log?.warn(`[fp] no route - check bindings for ${message.deviceId}`);
+                // Send error status to client
+                sendStatusUpdate({
+                  to: message.deviceId,
+                  messageId: message.messageId,
+                  status: "failed",
+                  message: "No agent route configured for this device",
+                });
                 return;
               }
 
@@ -477,6 +487,17 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
               });
               log?.info(`[fp] 8. session recorded, starting dispatch...`);
 
+              // ========== SEND "PROCESSING" STATUS ==========
+              sendStatusUpdate({
+                to: message.deviceId,
+                messageId: message.messageId,
+                status: "processing",
+                message: "Your message is being processed",
+                details: {
+                  startedAt: Date.now(),
+                },
+              });
+
               // Create dispatcher for replies
               const { sendTextMessage } = await import("./relay-client.js");
               const { dispatcher, replyOptions } = channelApi.reply.createReplyDispatcherWithTyping({
@@ -493,23 +514,83 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
                 },
                 onError: (err: Error) => {
                   log?.error(`[fp] reply delivery failed: ${err.message}`);
+                  // Send error status to client
+                  sendStatusUpdate({
+                    to: message.deviceId,
+                    messageId: message.messageId,
+                    status: "failed",
+                    message: `Failed to deliver reply: ${err.message}`,
+                  });
                 },
               });
 
-              // Dispatch to agent
-              await channelApi.reply.dispatchReplyFromConfig({
-                ctx: ctxPayload,
-                cfg,
-                dispatcher,
-                replyOptions,
-              });
-              log?.info(`[fp] 11. dispatch complete`);
+              // ========== DISPATCH WITH ENHANCED REPLY OPTIONS ==========
+              // Add callbacks to track agent progress
+              const enhancedReplyOptions = {
+                ...replyOptions,
+                onAgentRunStart: (runId: string) => {
+                  log?.info(`[fp] agent run started: ${runId}`);
+                },
+                onToolResult: (payload: { name?: string }) => {
+                  log?.info(`[fp] tool executed: ${payload.name}`);
+                },
+              };
+
+              try {
+                // Dispatch to agent
+                await channelApi.reply.dispatchReplyFromConfig({
+                  ctx: ctxPayload,
+                  cfg,
+                  dispatcher,
+                  replyOptions: enhancedReplyOptions,
+                });
+
+                const dispatchDuration = Date.now() - dispatchStartTime;
+                log?.info(`[fp] 11. dispatch complete (took ${dispatchDuration}ms)`);
+
+                // Send completion status
+                sendStatusUpdate({
+                  to: message.deviceId,
+                  messageId: message.messageId,
+                  status: "completed",
+                  message: "Response delivered",
+                  details: {
+                    durationMs: dispatchDuration,
+                  },
+                });
+              } catch (dispatchError) {
+                const err = dispatchError as Error;
+                log?.error(`[fp] dispatch failed: ${err.message}`);
+
+                // Send error status to client
+                sendStatusUpdate({
+                  to: message.deviceId,
+                  messageId: message.messageId,
+                  status: "failed",
+                  message: err.message.includes("timed out")
+                    ? "Request timed out. The AI is taking longer than expected."
+                    : `Error: ${err.message}`,
+                  details: {
+                    errorType: err.message.includes("timed out") ? "timeout" : "error",
+                    durationMs: Date.now() - dispatchStartTime,
+                  },
+                });
+              }
               return;
             }
 
             // Fallback: agent.enqueueInbound
             if ((globalRuntime as any).agent?.enqueueInbound) {
               log?.info(`[fp] fallback: using agent.enqueueInbound`);
+
+              // Send processing status
+              sendStatusUpdate({
+                to: message.deviceId,
+                messageId: message.messageId,
+                status: "processing",
+                message: "Your message is being processed",
+              });
+
               const { sendTextMessage } = await import("./relay-client.js");
               await (globalRuntime as any).agent.enqueueInbound({
                 channel: "firstperson",
@@ -532,6 +613,13 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
                     text,
                     replyTo: message.messageId,
                   });
+                  // Send completion status
+                  sendStatusUpdate({
+                    to: message.deviceId,
+                    messageId: message.messageId,
+                    status: "completed",
+                    message: "Response delivered",
+                  });
                 },
               });
               return;
@@ -540,6 +628,15 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
             // Fallback: gateway.handleInbound
             if ((globalRuntime as any).gateway?.handleInbound) {
               log?.info(`[fp] fallback: using gateway.handleInbound`);
+
+              // Send processing status
+              sendStatusUpdate({
+                to: message.deviceId,
+                messageId: message.messageId,
+                status: "processing",
+                message: "Your message is being processed",
+              });
+
               const { sendTextMessage } = await import("./relay-client.js");
               await (globalRuntime as any).gateway.handleInbound({
                 channel: "firstperson",
@@ -557,15 +654,35 @@ export const firstPersonPlugin: ChannelPlugin<ResolvedFirstPersonAccount> = {
                     text,
                     replyTo: message.messageId,
                   });
+                  // Send completion status
+                  sendStatusUpdate({
+                    to: message.deviceId,
+                    messageId: message.messageId,
+                    status: "completed",
+                    message: "Response delivered",
+                  });
                 },
               });
               return;
             }
 
             log?.error(`[fp] ERROR: no dispatch method available on runtime`);
+            sendStatusUpdate({
+              to: message.deviceId,
+              messageId: message.messageId,
+              status: "failed",
+              message: "No dispatch method available",
+            });
 
           } catch (err) {
             log?.error(`[fp] ERROR processing message: ${err}`);
+            // Send error status to client
+            sendStatusUpdate({
+              to: message.deviceId,
+              messageId: message.messageId,
+              status: "failed",
+              message: `Error processing message: ${(err as Error).message}`,
+            });
           }
         },
       });

package/src/relay-client.ts

@@ -29,6 +29,30 @@ export interface SendMessageResult {
   chatId: string;
 }
 
+/**
+ * Message status types matching the relay protocol
+ */
+export type MessageStatus =
+  | "received"
+  | "forwarded"
+  | "processing"
+  | "completed"
+  | "failed"
+  | "gateway_offline";
+
+/**
+ * Status message sent to relay for forwarding to iOS client
+ */
+export interface StatusUpdate {
+  type: "message_status";
+  messageId: string;
+  to: string;
+  status: MessageStatus;
+  message?: string;
+  timestamp: number;
+  details?: Record<string, unknown>;
+}
+
 // Store active connection and pending reply callbacks
 let activeWs: WebSocket | null = null;
 let activeLogger: Logger | null = null;
@@ -43,6 +67,45 @@ function log(level: "info" | "warn" | "error", msg: string): void {
   }
 }
 
+/**
+ * Send a status update for a message to the relay.
+ * The relay will forward this to the iOS client.
+ */
+export function sendStatusUpdate(params: {
+  to: string;
+  messageId: string;
+  status: MessageStatus;
+  message?: string;
+  details?: Record<string, unknown>;
+}): void {
+  const { to, messageId, status, message, details } = params;
+
+  if (!activeWs || activeWs.readyState !== WebSocket.OPEN) {
+    log("warn", `[relay-client] Cannot send status update - no active connection`);
+    return;
+  }
+
+  const statusMsg: StatusUpdate = {
+    type: "message_status",
+    messageId,
+    to,
+    status,
+    timestamp: Date.now(),
+    ...(message && { message }),
+    ...(details && { details }),
+  };
+
+  activeWs.send(JSON.stringify(statusMsg));
+  log("info", `[relay-client] Sent status update: ${status} for message ${messageId} to ${to}`);
+}
+
+/**
+ * Check if the relay connection is active
+ */
+export function isRelayConnected(): boolean {
+  return activeWs !== null && activeWs.readyState === WebSocket.OPEN;
+}
+
 export async function sendTextMessage(params: {
   relayUrl: string;
   token: string;
@@ -142,9 +205,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 +233,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 +268,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 +314,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 +332,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 +352,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;