@firstperson/firstperson 2026.1.34 → 2026.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstperson/firstperson",
-  "version": "2026.1.34",
+  "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;