refactor: centralize presence routing and version precedence coverage (#19609)

Merged via /review-pr -> /prepare-pr -> /merge-pr.

Prepared head SHA: 10d9df5263
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Co-authored-by: gumadeiras <5599352+gumadeiras@users.noreply.github.com>
Reviewed-by: @gumadeiras

src/gateway/server/presence-events.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { broadcastPresenceSnapshot } from "./presence-events.js";
+
+describe("broadcastPresenceSnapshot", () => {
+  it("increments version and broadcasts presence with state versions", () => {
+    const broadcast = vi.fn();
+    const incrementPresenceVersion = vi.fn(() => 7);
+    const getHealthVersion = vi.fn(() => 11);
+
+    const presenceVersion = broadcastPresenceSnapshot({
+      broadcast,
+      incrementPresenceVersion,
+      getHealthVersion,
+    });
+
+    expect(presenceVersion).toBe(7);
+    expect(incrementPresenceVersion).toHaveBeenCalledTimes(1);
+    expect(getHealthVersion).toHaveBeenCalledTimes(1);
+    expect(broadcast).toHaveBeenCalledTimes(1);
+
+    const [event, payload, opts] = broadcast.mock.calls[0] as [
+      string,
+      unknown,
+      { dropIfSlow?: boolean; stateVersion?: { presence?: number; health?: number } } | undefined,
+    ];
+
+    expect(event).toBe("presence");
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+      throw new Error("expected object payload");
+    }
+    expect(Array.isArray((payload as { presence?: unknown }).presence)).toBe(true);
+    expect(opts?.dropIfSlow).toBe(true);
+    expect(opts?.stateVersion).toEqual({ presence: 7, health: 11 });
+  });
+});

src/gateway/server/presence-events.ts

@@ -0,0 +1,22 @@
+import { listSystemPresence } from "../../infra/system-presence.js";
+import type { GatewayBroadcastFn } from "../server-broadcast.js";
+
+export function broadcastPresenceSnapshot(params: {
+  broadcast: GatewayBroadcastFn;
+  incrementPresenceVersion: () => number;
+  getHealthVersion: () => number;
+}): number {
+  const presenceVersion = params.incrementPresenceVersion();
+  params.broadcast(
+    "presence",
+    { presence: listSystemPresence() },
+    {
+      dropIfSlow: true,
+      stateVersion: {
+        presence: presenceVersion,
+        health: params.getHealthVersion(),
+      },
+    },
+  );
+  return presenceVersion;
+}

src/gateway/server/ws-connection.ts

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import type { WebSocket, WebSocketServer } from "ws";
 import { resolveCanvasHostUrl } from "../../infra/canvas-host-url.js";
 import { removeRemoteNodeInfo } from "../../infra/skills-remote.js";
-import { listSystemPresence, upsertPresence } from "../../infra/system-presence.js";
+import { upsertPresence } from "../../infra/system-presence.js";
 import type { createSubsystemLogger } from "../../logging/subsystem.js";
 import { truncateUtf16Safe } from "../../utils.js";
 import { isWebchatClient } from "../../utils/message-channel.js";
@@ -13,7 +13,8 @@ import { getHandshakeTimeoutMs } from "../server-constants.js";
 import type { GatewayRequestContext, GatewayRequestHandlers } from "../server-methods/types.js";
 import { formatError } from "../server-utils.js";
 import { logWs } from "../ws-log.js";
-import { getHealthVersion, getPresenceVersion, incrementPresenceVersion } from "./health-state.js";
+import { getHealthVersion, incrementPresenceVersion } from "./health-state.js";
+import { broadcastPresenceSnapshot } from "./presence-events.js";
 import { attachGatewayWsMessageHandler } from "./ws-connection/message-handler.js";
 import type { GatewayWsClient } from "./ws-types.js";
 
@@ -227,18 +228,7 @@ export function attachGatewayWsConnectionHandler(params: {
       }
       if (client?.presenceKey) {
         upsertPresence(client.presenceKey, { reason: "disconnect" });
-        incrementPresenceVersion();
-        broadcast(
-          "presence",
-          { presence: listSystemPresence() },
-          {
-            dropIfSlow: true,
-            stateVersion: {
-              presence: getPresenceVersion(),
-              health: getHealthVersion(),
-            },
-          },
-        );
+        broadcastPresenceSnapshot({ broadcast, incrementPresenceVersion, getHealthVersion });
       }
       if (client?.connect?.role === "node") {
         const context = buildRequestContext();

src/gateway/server/ws-connection/message-handler.ts

@@ -22,6 +22,7 @@ import { loadVoiceWakeConfig } from "../../../infra/voicewake.js";
 import { rawDataToString } from "../../../infra/ws.js";
 import type { createSubsystemLogger } from "../../../logging/subsystem.js";
 import { isGatewayCliClient, isWebchatClient } from "../../../utils/message-channel.js";
+import { resolveRuntimeServiceVersion } from "../../../version.js";
 import {
   AUTH_RATE_LIMIT_SCOPE_DEVICE_TOKEN,
   AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET,
@@ -791,7 +792,7 @@ export function attachGatewayWsMessageHandler(params: {
           type: "hello-ok",
           protocol: PROTOCOL_VERSION,
           server: {
-            version: process.env.OPENCLAW_VERSION ?? process.env.npm_package_version ?? "dev",
+            version: resolveRuntimeServiceVersion(process.env, "dev"),
             commit: process.env.GIT_COMMIT,
             host: os.hostname(),
             connId,