@firstperson/firstperson 2026.1.33

package/src/relay-client.ts

@@ -0,0 +1,266 @@
+import WebSocket from "ws";
+
+export interface Logger {
+  info: (msg: string) => void;
+  warn: (msg: string) => void;
+  error: (msg: string) => void;
+}
+
+export interface IncomingMessage {
+  messageId: string;
+  deviceId: string;
+  text: string;
+  timestamp?: string;
+}
+
+export interface RelayConnectionParams {
+  relayUrl: string;
+  token: string;
+  accountId: string;
+  abortSignal: AbortSignal;
+  log?: Logger;
+  onConnected: () => void;
+  onDisconnected: (error?: Error) => void;
+  onMessage: (message: IncomingMessage) => Promise<void>;
+}
+
+export interface SendMessageResult {
+  messageId: string;
+  chatId: string;
+}
+
+// Store active connection and pending reply callbacks
+let activeWs: WebSocket | null = null;
+let activeLogger: Logger | null = null;
+const pendingReplies = new Map<
+  string,
+  { resolve: (result: SendMessageResult) => void; reject: (err: Error) => void; to: string }
+>();
+
+function log(level: "info" | "warn" | "error", msg: string): void {
+  if (activeLogger) {
+    activeLogger[level](msg);
+  }
+}
+
+export async function sendTextMessage(params: {
+  relayUrl: string;
+  token: string;
+  to: string;
+  text: string;
+  replyTo?: string;
+}): Promise<SendMessageResult> {
+  const { to, text, replyTo } = params;
+
+  // Use active connection if available
+  if (activeWs && activeWs.readyState === WebSocket.OPEN) {
+    const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    return new Promise((resolve, reject) => {
+      // Store callback for when we get acknowledgment
+      pendingReplies.set(messageId, { resolve, reject, to });
+
+      activeWs!.send(
+        JSON.stringify({
+          type: "message",
+          to,
+          text,
+          messageId,
+          ...(replyTo && { replyTo }),
+        })
+      );
+
+      // Timeout after 30 seconds
+      setTimeout(() => {
+        if (pendingReplies.has(messageId)) {
+          pendingReplies.delete(messageId);
+          resolve({ messageId, chatId: to }); // Assume sent if no error
+        }
+      }, 30000);
+    });
+  }
+
+  // Fallback: create temporary connection if no active connection
+  // This handles cases like pairing approval before gateway starts
+  const { relayUrl, token } = params;
+
+  return new Promise((resolve, reject) => {
+    const wsUrl = `${relayUrl}/ws/gateway?token=${encodeURIComponent(token)}`;
+    const ws = new WebSocket(wsUrl);
+
+    const messageId = `msg_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    ws.on("open", () => {
+      ws.send(
+        JSON.stringify({
+          type: "message",
+          to,
+          text,
+          messageId,
+          ...(replyTo && { replyTo }),
+        })
+      );
+    });
+
+    ws.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === "message_sent" || msg.type === "ack") {
+          ws.close();
+          resolve({ messageId, chatId: to });
+        } else if (msg.type === "error") {
+          ws.close();
+          reject(new Error(msg.error ?? "Send failed"));
+        }
+      } catch {
+        // Ignore parse errors for non-JSON messages
+      }
+    });
+
+    ws.on("error", (err) => {
+      reject(err);
+    });
+
+    // Timeout after 30 seconds
+    setTimeout(() => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.close();
+        resolve({ messageId, chatId: to }); // Assume sent if no error
+      }
+    }, 30000);
+  });
+}
+
+export async function startRelayConnection(params: RelayConnectionParams): Promise<void> {
+  const { relayUrl, token, abortSignal, onConnected, onDisconnected, onMessage, log: logger } =
+    params;
+
+  // Store logger for use by sendTextMessage
+  activeLogger = logger ?? null;
+
+  const wsUrl = `${relayUrl}/ws/gateway?token=${encodeURIComponent(token)}`;
+
+  let ws: WebSocket | null = null;
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = 10;
+  const baseReconnectDelay = 1000;
+
+  const connect = () => {
+    if (abortSignal.aborted) {
+      log("info", "[relay-client] connect() called but abortSignal already aborted");
+      return;
+    }
+
+    log("info", `[relay-client] Creating WebSocket connection to: ${wsUrl.replace(/token=[^&]+/, "token=***")}`);
+    ws = new WebSocket(wsUrl);
+
+    ws.on("open", () => {
+      log("info", `[relay-client] WebSocket opened, readyState: ${ws?.readyState}`);
+      reconnectAttempts = 0;
+      activeWs = ws; // Store as active connection for sending
+      onConnected();
+    });
+
+    ws.on("message", async (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        log("info", `[relay-client] Received message type: ${msg.type}`);
+
+        if (msg.type === "ping") {
+          log("info", "[relay-client] Responding to ping with pong");
+          ws?.send(JSON.stringify({ type: "pong" }));
+          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);
+          if (pending) {
+            pending.resolve({ messageId: msg.messageId, chatId: pending.to });
+            pendingReplies.delete(msg.messageId);
+          }
+          return;
+        }
+
+        // Handle send errors
+        if (msg.type === "error" && msg.messageId) {
+          const pending = pendingReplies.get(msg.messageId);
+          if (pending) {
+            pending.reject(new Error(msg.error ?? "Send failed"));
+            pendingReplies.delete(msg.messageId);
+          }
+          return;
+        }
+
+        // Handle incoming messages
+        if (msg.type === "message" && msg.from && msg.text) {
+          await onMessage({
+            messageId: msg.messageId ?? `msg_${Date.now()}`,
+            deviceId: msg.from,
+            text: msg.text,
+            timestamp: msg.timestamp,
+          });
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    });
+
+    ws.on("close", (code, reason) => {
+      log(
+        "info",
+        `[relay-client] WebSocket closed - code: ${code} reason: ${reason?.toString() || "(none)"} wasClean: ${code === 1000}`
+      );
+      log("info", `[relay-client] abortSignal.aborted: ${abortSignal.aborted}`);
+
+      // Clear active connection and reject pending replies
+      if (activeWs === ws) {
+        activeWs = null;
+      }
+      for (const [, pending] of pendingReplies) {
+        pending.reject(new Error("Connection closed"));
+      }
+      pendingReplies.clear();
+
+      if (abortSignal.aborted) {
+        log("info", "[relay-client] Connection closed due to abort signal");
+        onDisconnected();
+        return;
+      }
+
+      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"));
+      }
+    });
+
+    ws.on("error", (err) => {
+      log("error", `[relay-client] WebSocket error: ${err.message}`);
+      // Error will trigger close event
+    });
+  };
+
+  // Handle abort signal
+  abortSignal.addEventListener("abort", () => {
+    log("info", "[relay-client] Abort signal received, closing WebSocket");
+    if (activeWs === ws) {
+      activeWs = null;
+      activeLogger = null;
+    }
+    if (ws) {
+      ws.close();
+      ws = null;
+    }
+  });
+
+  connect();
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setFirstPersonRuntime(r: PluginRuntime): void {
+  runtime = r;
+}
+
+export function getFirstPersonRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("First Person runtime not initialized - plugin not registered");
+  }
+  return runtime;
+}

package/src/types.ts

@@ -0,0 +1,32 @@
+export type DmPolicy = "pairing" | "allowlist" | "open" | "disabled";
+
+export type FirstPersonConfig = {
+  /** If false, do not start First Person. Default: true. */
+  enabled?: boolean;
+  /** Gateway authentication token for relay connection. */
+  token?: string;
+  /** WebSocket relay URL. Default: wss://chat.firstperson.ai */
+  relayUrl?: string;
+  /** DM access policy. Default: pairing. */
+  dmPolicy?: DmPolicy;
+  /** Allowlist of approved device IDs. */
+  allowFrom?: Array<string | number>;
+};
+
+export type ResolvedFirstPersonAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  token: string | null;
+  relayUrl: string;
+  config: FirstPersonConfig;
+  tokenSource: "config" | "env" | "none";
+};
+
+export type CoreConfig = {
+  channels?: {
+    firstperson?: FirstPersonConfig;
+  };
+  [key: string]: unknown;
+};

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "."
+  },
+  "include": ["index.ts", "src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: ["src/**/*.test.ts"],
+      thresholds: {
+        lines: 70,
+        branches: 70,
+        functions: 70,
+        statements: 70,
+      },
+    },
+  },
+});