@privateclaw/privateclaw-relay 0.1.6 → 0.1.8

package/dist/relay-server.js

@@ -1,14 +1,21 @@
 import { randomUUID } from "node:crypto";
 import { createServer, } from "node:http";
 import { WebSocket, WebSocketServer } from "ws";
+import { handleRelayAdminRequest } from "./admin-api.js";
+import { createRelayAdminMetricsStore, } from "./admin-metrics-store.js";
 import { createEncryptedFrameCache, } from "./frame-cache.js";
 import { createRelayPushRegistrationStore, } from "./push-registration-store.js";
 import { createRelayPushNotifier, } from "./push-notifier.js";
 import { createRedisRelayClusterClient, RelayClaimConflictError, } from "./relay-cluster.js";
 import { createRelaySessionStore, } from "./session-store.js";
-import { serveRelayWebRequest } from "./relay-web.js";
+import { resolveRelayAdminWebRootDir, serveRelayWebRequest, } from "./relay-web.js";
 const HEARTBEAT_INTERVAL_MS = 15_000;
 const PUSH_WAKE_COOLDOWN_MS = 5_000;
+const DEFAULT_PROTOCOL_MESSAGE_BYTES = 24 * 1024 * 1024;
+const DEFAULT_APP_MESSAGES_PER_MINUTE = 120;
+const DEFAULT_PROVIDER_MESSAGES_PER_MINUTE = 600;
+const MESSAGE_SIZE_SLACK_BYTES = 1 * 1024 * 1024;
+const APP_MESSAGE_RATE_LIMIT_WINDOW_MS = 60_000;
 class RelayProtocolError extends Error {
     code;
     constructor(code, message) {
@@ -44,6 +51,101 @@ function parseJson(raw) {
         throw new RelayProtocolError("invalid_json", "Relay messages must be valid JSON.");
     }
 }
+function assertMessageSizeWithinLimit(raw, maxBytes, actorLabel) {
+    const rawBytes = Buffer.byteLength(raw, "utf8");
+    if (rawBytes <= maxBytes) {
+        return;
+    }
+    throw new RelayProtocolError("message_too_large", `${actorLabel} message exceeds the ${maxBytes}-byte relay limit.`);
+}
+class FixedWindowRateLimiter {
+    params;
+    entries = new Map();
+    constructor(params) {
+        this.params = params;
+    }
+    now() {
+        return this.params.now?.() ?? Date.now();
+    }
+    async recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
+    allow(key) {
+        const now = this.now();
+        const existing = this.entries.get(key);
+        if (!existing || now - existing.windowStartedAt >= this.params.windowMs) {
+            this.entries.set(key, { count: 1, windowStartedAt: now });
+            this.prune(now);
+            return true;
+        }
+        if (existing.count >= this.params.maxPerWindow) {
+            this.prune(now);
+            return false;
+        }
+        existing.count += 1;
+        this.prune(now);
+        return true;
+    }
+    prune(now) {
+        if (this.entries.size < 512) {
+            return;
+        }
+        for (const [key, entry] of this.entries.entries()) {
+            if (now - entry.windowStartedAt >= this.params.windowMs * 2) {
+                this.entries.delete(key);
+            }
+        }
+    }
+}
+export class WakeCooldownTracker {
+    params;
+    entries = new Map();
+    constructor(params) {
+        this.params = params;
+    }
+    now() {
+        return this.params.now?.() ?? Date.now();
+    }
+    prune(now) {
+        const pruneAfterMs = this.params.pruneAfterMs ?? this.params.cooldownMs;
+        for (const [key, sentAt] of this.entries.entries()) {
+            if (now - sentAt >= pruneAfterMs) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    getLastSentAt(key) {
+        const now = this.now();
+        this.prune(now);
+        return this.entries.get(key);
+    }
+    recordSent(key) {
+        const now = this.now();
+        this.entries.set(key, now);
+        this.prune(now);
+    }
+    clearSession(sessionId, appId) {
+        if (appId) {
+            this.entries.delete(`${sessionId}:${appId}`);
+            return;
+        }
+        const prefix = `${sessionId}:`;
+        for (const key of this.entries.keys()) {
+            if (key.startsWith(prefix)) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    entryCount() {
+        this.prune(this.now());
+        return this.entries.size;
+    }
+}
 function toRelayProtocolError(error) {
     if (error instanceof RelayProtocolError) {
         return error;
@@ -87,10 +189,14 @@ class SessionHub {
     sessionProviders = new Map();
     sessionApps = new Map();
     appSessions = new Map();
-    recentWakeSentAt = new Map();
+    wakeCooldownTracker;
     cluster;
     constructor(params) {
         this.params = params;
+        this.wakeCooldownTracker = new WakeCooldownTracker({
+            cooldownMs: PUSH_WAKE_COOLDOWN_MS,
+            ...(params.now ? { now: params.now } : {}),
+        });
     }
     setCluster(cluster) {
         this.cluster = cluster;
@@ -98,20 +204,22 @@ class SessionHub {
     now() {
         return this.params.now?.() ?? Date.now();
     }
+    async recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
     wakeKey(sessionId, appId) {
         return `${sessionId}:${appId}`;
     }
     clearWakeState(sessionId, appId) {
-        if (appId) {
-            this.recentWakeSentAt.delete(this.wakeKey(sessionId, appId));
-            return;
-        }
-        const prefix = `${sessionId}:`;
-        for (const key of this.recentWakeSentAt.keys()) {
-            if (key.startsWith(prefix)) {
-                this.recentWakeSentAt.delete(key);
-            }
-        }
+        this.wakeCooldownTracker.clearSession(sessionId, appId);
+    }
+    getProviderRateLimitKey(providerSocket) {
+        return this.requireProviderId(providerSocket);
     }
     get usesPersistentSessions() {
         return this.params.sessionStore.persistent;
@@ -165,7 +273,7 @@ class SessionHub {
             await this.cluster.subscribeApp(binding.sessionId, binding.appId);
         }
     }
-    async forgetLocalAppBinding(appSocket, binding) {
+    async forgetLocalAppBinding(appSocket, binding, reason) {
         const appSockets = this.sessionApps.get(binding.sessionId);
         if (!appSockets || appSockets.get(binding.appId) !== appSocket) {
             this.appSessions.delete(appSocket);
@@ -180,6 +288,9 @@ class SessionHub {
             await this.cluster.unsubscribeApp(binding.sessionId, binding.appId);
             await this.cluster.releaseApp(binding);
         }
+        if (reason) {
+            await this.recordAdminMetric(() => this.params.adminMetricsStore.recordAppDetached(binding.sessionId, binding.appId, this.now(), reason), "app detach metrics");
+        }
         return true;
     }
     async attachProvider(providerId, providerSocket) {
@@ -219,6 +330,7 @@ class SessionHub {
         };
         await this.params.sessionStore.saveSession(session);
         await this.rememberLocalProviderSession(providerId, session.sessionId);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionCreated(session, this.now()), "session creation metrics");
         return session;
     }
     async requireSession(sessionId) {
@@ -267,6 +379,7 @@ class SessionHub {
         };
         await this.params.sessionStore.saveSession(renewedSession);
         await this.params.pushRegistrationStore.touchSession(sessionId, renewedSession.expiresAt);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionRenewed(renewedSession, this.now()), "session renewal metrics");
         return renewedSession;
     }
     async registerAppPushToken(sessionId, appId, token) {
@@ -331,13 +444,13 @@ class SessionHub {
         for (const registration of matchingRegistrations) {
             const wakeKey = this.wakeKey(registration.sessionId, registration.appId);
             const now = this.now();
-            const lastWakeSentAt = this.recentWakeSentAt.get(wakeKey);
+            const lastWakeSentAt = this.wakeCooldownTracker.getLastSentAt(wakeKey);
             if (lastWakeSentAt !== undefined &&
                 now - lastWakeSentAt < PUSH_WAKE_COOLDOWN_MS) {
                 console.info(`[privateclaw-relay] wake skipped: cooldown session=${registration.sessionId} appId=${registration.appId} sinceMs=${now - lastWakeSentAt}`);
                 continue;
             }
-            this.recentWakeSentAt.set(wakeKey, now);
+            this.wakeCooldownTracker.recordSent(wakeKey);
             try {
                 const result = await this.params.pushNotifier.sendWake(registration);
                 console.info(`[privateclaw-relay] wake sent session=${registration.sessionId} appId=${registration.appId} unregisterToken=${result.unregisterToken}`);
@@ -389,6 +502,7 @@ class SessionHub {
             }
         }
         await this.rememberLocalAppBinding(binding, appSocket);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordAppAttached(session, normalizedAppId, this.now()), "app attach metrics");
         return session;
     }
     deliverLocalToApp(sessionId, envelope, targetAppId) {
@@ -493,7 +607,7 @@ class SessionHub {
             if (!binding || binding.appId !== appId) {
                 continue;
             }
-            await this.forgetLocalAppBinding(appSocket, binding);
+            await this.forgetLocalAppBinding(appSocket, binding, reason);
             sendJson(appSocket, {
                 type: "relay:session_closed",
                 sessionId,
@@ -521,6 +635,7 @@ class SessionHub {
         await this.params.sessionStore.deleteSession(sessionId);
         await this.params.pushRegistrationStore.clearSession(sessionId);
         this.clearWakeState(sessionId);
+        await this.recordAdminMetric(() => this.params.adminMetricsStore.recordSessionClosed(sessionId, reason, this.now()), "session close metrics");
         if (!this.hasLocalSession(sessionId) && !this.cluster) {
             await this.params.frameCache.clear(sessionId);
             return;
@@ -571,7 +686,7 @@ class SessionHub {
         if (!binding) {
             return;
         }
-        await this.forgetLocalAppBinding(appSocket, binding);
+        await this.forgetLocalAppBinding(appSocket, binding, "app_disconnected");
     }
     async closeLocalApp(sessionId, appId, reason) {
         const appSocket = this.sessionApps.get(sessionId)?.get(appId);
@@ -582,7 +697,7 @@ class SessionHub {
         if (!binding) {
             return;
         }
-        await this.forgetLocalAppBinding(appSocket, binding);
+        await this.forgetLocalAppBinding(appSocket, binding, reason);
         sendJson(appSocket, {
             type: "relay:session_closed",
             sessionId,
@@ -644,6 +759,36 @@ class SessionHub {
             appBindings,
         });
     }
+    getAdminLocalSnapshot() {
+        const providerIds = [...this.providerSockets.entries()]
+            .filter(([, socket]) => socket.readyState === WebSocket.OPEN)
+            .map(([providerId]) => providerId)
+            .sort();
+        const participantBindings = [];
+        const sessionIds = new Set(this.sessionProviders.keys());
+        for (const [appSocket, binding] of this.appSessions.entries()) {
+            const currentSocket = this.sessionApps.get(binding.sessionId)?.get(binding.appId);
+            if (currentSocket !== appSocket || appSocket.readyState !== WebSocket.OPEN) {
+                continue;
+            }
+            participantBindings.push({
+                sessionId: binding.sessionId,
+                appId: binding.appId,
+            });
+            sessionIds.add(binding.sessionId);
+        }
+        participantBindings.sort((left, right) => left.sessionId.localeCompare(right.sessionId) ||
+            left.appId.localeCompare(right.appId));
+        return {
+            activeProviders: providerIds.length,
+            activeApps: participantBindings.length,
+            localSessions: sessionIds.size,
+            providerIds,
+            sessionIds: [...sessionIds].sort(),
+            participantBindings,
+            memoryUsage: process.memoryUsage(),
+        };
+    }
     async closeAll(reason) {
         const sessionIds = new Set([
             ...this.sessionProviders.keys(),
@@ -655,6 +800,10 @@ class SessionHub {
     }
 }
 export function createRelayServer(config, deps = {}) {
+    const maxMessageBytes = config.maxMessageBytes ?? DEFAULT_PROTOCOL_MESSAGE_BYTES;
+    const appMessagesPerMinute = config.appMessagesPerMinute ?? DEFAULT_APP_MESSAGES_PER_MINUTE;
+    const providerMessagesPerMinute = config.providerMessagesPerMinute ?? DEFAULT_PROVIDER_MESSAGES_PER_MINUTE;
+    const websocketMaxPayloadBytes = maxMessageBytes + MESSAGE_SIZE_SLACK_BYTES;
     const ownsFrameCache = !deps.frameCache;
     const frameCache = deps.frameCache ??
         createEncryptedFrameCache({
@@ -679,12 +828,31 @@ export function createRelayServer(config, deps = {}) {
             fcmClientEmail: config.fcmClientEmail,
             fcmPrivateKey: config.fcmPrivateKey,
         });
+    const ownsAdminMetricsStore = !deps.adminMetricsStore;
+    const adminMetricsStore = deps.adminMetricsStore ??
+        createRelayAdminMetricsStore({
+            ...(config.redisUrl ? { redisUrl: config.redisUrl } : {}),
+        });
+    const relayStartedAt = Date.now();
+    const adminWebRootDir = config.adminToken &&
+        (config.adminWebRootDir ?? resolveRelayAdminWebRootDir());
     const sessionHub = new SessionHub({
         defaultTtlMs: config.sessionTtlMs,
         frameCache,
         sessionStore,
         pushRegistrationStore,
         pushNotifier,
+        adminMetricsStore,
+        ...(deps.now ? { now: deps.now } : {}),
+    });
+    const appMessageRateLimiter = new FixedWindowRateLimiter({
+        maxPerWindow: appMessagesPerMinute,
+        windowMs: APP_MESSAGE_RATE_LIMIT_WINDOW_MS,
+        ...(deps.now ? { now: deps.now } : {}),
+    });
+    const providerMessageRateLimiter = new FixedWindowRateLimiter({
+        maxPerWindow: providerMessagesPerMinute,
+        windowMs: APP_MESSAGE_RATE_LIMIT_WINDOW_MS,
         ...(deps.now ? { now: deps.now } : {}),
     });
     const clusterCallbacks = {
@@ -722,6 +890,22 @@ export function createRelayServer(config, deps = {}) {
     let startedPort = config.port;
     let startedUrl = "";
     let started = false;
+    async function recordAdminMetric(action, label) {
+        try {
+            await action();
+        }
+        catch (error) {
+            console.error(`[privateclaw-relay] failed to record ${label}`, error);
+        }
+    }
+    async function recordInstanceHeartbeat() {
+        await recordAdminMetric(() => adminMetricsStore.recordInstanceHeartbeat({
+            instanceId: clusterNodeId,
+            startedAt: relayStartedAt,
+            recordedAt: deps.now?.() ?? Date.now(),
+            snapshot: sessionHub.getAdminLocalSnapshot(),
+        }), "relay instance heartbeat");
+    }
     async function handleHttpRequest(request, response) {
         const url = new URL(request.url ?? "/", `http://${request.headers.host ?? `${config.host}:${startedPort}`}`);
         try {
@@ -732,6 +916,29 @@ export function createRelayServer(config, deps = {}) {
                 response.end(JSON.stringify({ ok: true, sessions, instanceId: clusterNodeId }));
                 return;
             }
+            const handledAdminApi = await handleRelayAdminRequest({
+                request,
+                response,
+                url,
+                metricsStore: adminMetricsStore,
+                ...(config.adminToken ? { adminToken: config.adminToken } : {}),
+                ...(deps.now ? { now: deps.now } : {}),
+            });
+            if (handledAdminApi) {
+                return;
+            }
+            if (adminWebRootDir && url.pathname.startsWith("/admin")) {
+                const handledAdminWeb = await serveRelayWebRequest({
+                    request,
+                    response,
+                    url,
+                    webRootDir: adminWebRootDir,
+                    mountPath: "/admin",
+                });
+                if (handledAdminWeb) {
+                    return;
+                }
+            }
             if (config.webRootDir) {
                 const handled = await serveRelayWebRequest({
                     request,
@@ -762,8 +969,14 @@ export function createRelayServer(config, deps = {}) {
     const server = createServer((request, response) => {
         void handleHttpRequest(request, response);
     });
-    const providerWss = new WebSocketServer({ noServer: true });
-    const appWss = new WebSocketServer({ noServer: true });
+    const providerWss = new WebSocketServer({
+        noServer: true,
+        maxPayload: websocketMaxPayloadBytes,
+    });
+    const appWss = new WebSocketServer({
+        noServer: true,
+        maxPayload: websocketMaxPayloadBytes,
+    });
     const expiryTimer = setInterval(() => {
         void sessionHub.purgeExpiredSessions().catch((error) => {
             console.error("[privateclaw-relay] failed to purge expired sessions", error);
@@ -775,6 +988,7 @@ export function createRelayServer(config, deps = {}) {
         void sessionHub.refreshClusterPresence().catch((error) => {
             console.error("[privateclaw-relay] failed to refresh relay presence", error);
         });
+        void recordInstanceHeartbeat();
     }, HEARTBEAT_INTERVAL_MS);
     function terminateSockets(server) {
         for (const socket of server.clients) {
@@ -788,11 +1002,23 @@ export function createRelayServer(config, deps = {}) {
     }
     async function handleProviderMessage(socket, raw) {
         let requestId;
+        let requestType = "unknown";
         try {
+            assertMessageSizeWithinLimit(raw, maxMessageBytes, "Provider");
             const message = parseJson(raw);
             if (!isObject(message) || typeof message.type !== "string") {
                 throw new RelayProtocolError("invalid_message", "Provider message is missing a type field.");
             }
+            requestType = message.type;
+            if ("requestId" in message &&
+                typeof message.requestId === "string" &&
+                message.requestId !== "") {
+                requestId = message.requestId;
+            }
+            const providerRateLimitKey = sessionHub.getProviderRateLimitKey(socket);
+            if (!providerMessageRateLimiter.allow(providerRateLimitKey)) {
+                throw new RelayProtocolError("rate_limit_exceeded", "Too many provider messages. Slow down and retry.");
+            }
             switch (message.type) {
                 case "provider:create_session": {
                     const requestIdValue = message.requestId;
@@ -824,6 +1050,12 @@ export function createRelayServer(config, deps = {}) {
                         sessionId: session.sessionId,
                         expiresAt: new Date(session.expiresAt).toISOString(),
                     });
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:renew_session": {
@@ -847,6 +1079,12 @@ export function createRelayServer(config, deps = {}) {
                         sessionId: session.sessionId,
                         expiresAt: new Date(session.expiresAt).toISOString(),
                     });
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:frame": {
@@ -858,7 +1096,16 @@ export function createRelayServer(config, deps = {}) {
                         typeof message.targetAppId !== "string") {
                         throw new RelayProtocolError("invalid_target_app_id", "provider:frame targetAppId must be a string when provided.");
                     }
-                    await sessionHub.forwardToApp(socket, message.sessionId, message.envelope, message.targetAppId);
+                    const sessionIdValue = message.sessionId;
+                    await sessionHub.forwardToApp(socket, sessionIdValue, message.envelope, message.targetAppId);
+                    await recordAdminMetric(async () => {
+                        await adminMetricsStore.recordProviderFrame(sessionIdValue, deps.now?.() ?? Date.now());
+                        await adminMetricsStore.recordRequest({
+                            actor: "provider",
+                            type: requestType,
+                            ok: true,
+                        });
+                    }, "provider frame metrics");
                     return;
                 }
                 case "provider:close_session": {
@@ -868,6 +1115,12 @@ export function createRelayServer(config, deps = {}) {
                     await sessionHub.closeSessionForProvider(socket, message.sessionId, typeof message.reason === "string"
                         ? message.reason
                         : "provider_closed");
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 case "provider:close_app": {
@@ -879,6 +1132,12 @@ export function createRelayServer(config, deps = {}) {
                     await sessionHub.closeAppForProvider(socket, message.sessionId, message.appId, typeof message.reason === "string"
                         ? message.reason
                         : "provider_closed_app");
+                    await recordInstanceHeartbeat();
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "provider",
+                        type: requestType,
+                        ok: true,
+                    }), "provider request metrics");
                     return;
                 }
                 default:
@@ -887,6 +1146,14 @@ export function createRelayServer(config, deps = {}) {
         }
         catch (error) {
             const relayError = toRelayProtocolError(error);
+            await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                actor: "provider",
+                type: requestType === "unknown" && relayError.code === "invalid_json"
+                    ? "invalid_json"
+                    : requestType,
+                ok: false,
+                errorCode: relayError.code,
+            }), "provider error metrics");
             sendJson(socket, {
                 type: "relay:error",
                 code: relayError.code,
@@ -896,26 +1163,50 @@ export function createRelayServer(config, deps = {}) {
         }
     }
     async function handleAppMessage(socket, sessionId, appId, raw) {
+        let requestType = "unknown";
         try {
+            assertMessageSizeWithinLimit(raw, maxMessageBytes, "App");
+            if (!appMessageRateLimiter.allow(`${sessionId}:${appId}`)) {
+                throw new RelayProtocolError("rate_limit_exceeded", "Too many app messages. Slow down and retry.");
+            }
             const message = parseJson(raw);
             if (!isObject(message) || typeof message.type !== "string") {
                 throw new RelayProtocolError("invalid_message", "App message is missing a type field.");
             }
+            requestType = message.type;
             switch (message.type) {
                 case "app:frame":
                     if (!isEncryptedEnvelope(message.envelope)) {
                         throw new RelayProtocolError("invalid_frame", "app:frame must include a valid encrypted envelope.");
                     }
                     await sessionHub.forwardToProvider(sessionId, message.envelope);
+                    await recordAdminMetric(async () => {
+                        await adminMetricsStore.recordAppFrame(sessionId, appId, deps.now?.() ?? Date.now());
+                        await adminMetricsStore.recordRequest({
+                            actor: "app",
+                            type: requestType,
+                            ok: true,
+                        });
+                    }, "app frame metrics");
                     return;
                 case "app:register_push":
                     if (typeof message.token !== "string") {
                         throw new RelayProtocolError("invalid_push_token", "app:register_push requires a string token.");
                     }
                     await sessionHub.registerAppPushToken(sessionId, appId, message.token);
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "app",
+                        type: requestType,
+                        ok: true,
+                    }), "app request metrics");
                     return;
                 case "app:unregister_push":
                     await sessionHub.unregisterAppPushToken(sessionId, appId);
+                    await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                        actor: "app",
+                        type: requestType,
+                        ok: true,
+                    }), "app request metrics");
                     return;
                 default:
                     throw new RelayProtocolError("unsupported_message", `Unsupported app message type: ${String(message.type)}`);
@@ -923,6 +1214,14 @@ export function createRelayServer(config, deps = {}) {
         }
         catch (error) {
             const relayError = toRelayProtocolError(error);
+            await recordAdminMetric(() => adminMetricsStore.recordRequest({
+                actor: "app",
+                type: requestType === "unknown" && relayError.code === "invalid_json"
+                    ? "invalid_json"
+                    : requestType,
+                ok: false,
+                errorCode: relayError.code,
+            }), "app error metrics");
             sendJson(socket, {
                 type: "relay:error",
                 code: relayError.code,
@@ -939,6 +1238,7 @@ export function createRelayServer(config, deps = {}) {
         void (async () => {
             try {
                 await sessionHub.attachProvider(providerId, socket);
+                await recordInstanceHeartbeat();
             }
             catch (error) {
                 const relayError = toRelayProtocolError(error);
@@ -958,9 +1258,15 @@ export function createRelayServer(config, deps = {}) {
                 void handleProviderMessage(socket, data.toString());
             });
             socket.on("close", () => {
-                void sessionHub.detachProvider(socket).catch((error) => {
-                    console.error("[privateclaw-relay] failed to detach provider socket", error);
-                });
+                void (async () => {
+                    try {
+                        await sessionHub.detachProvider(socket);
+                    }
+                    catch (error) {
+                        console.error("[privateclaw-relay] failed to detach provider socket", error);
+                    }
+                    await recordInstanceHeartbeat();
+                })();
             });
         })();
     });
@@ -983,6 +1289,7 @@ export function createRelayServer(config, deps = {}) {
             let session;
             try {
                 session = await sessionHub.attachApp(sessionId, appId, socket);
+                await recordInstanceHeartbeat();
             }
             catch (error) {
                 const relayError = toRelayProtocolError(error);
@@ -1007,9 +1314,15 @@ export function createRelayServer(config, deps = {}) {
                 void handleAppMessage(socket, sessionId, appId, data.toString());
             });
             socket.on("close", () => {
-                void sessionHub.detachApp(socket).catch((error) => {
-                    console.error("[privateclaw-relay] failed to detach app socket", error);
-                });
+                void (async () => {
+                    try {
+                        await sessionHub.detachApp(socket);
+                    }
+                    catch (error) {
+                        console.error("[privateclaw-relay] failed to detach app socket", error);
+                    }
+                    await recordInstanceHeartbeat();
+                })();
             });
         })();
     });
@@ -1046,6 +1359,9 @@ export function createRelayServer(config, deps = {}) {
         if (ownsFrameCache) {
             closes.push(frameCache.close());
         }
+        if (ownsAdminMetricsStore) {
+            closes.push(adminMetricsStore.close());
+        }
         await Promise.all(closes);
     }
     return {
@@ -1073,6 +1389,7 @@ export function createRelayServer(config, deps = {}) {
             startedPort = address.port;
             startedUrl = `http://${config.host}:${startedPort}`;
             started = true;
+            await recordInstanceHeartbeat();
             return { port: startedPort, url: startedUrl };
         },
         async stop() {
@@ -1100,6 +1417,7 @@ export function createRelayServer(config, deps = {}) {
                     resolve();
                 });
             });
+            await recordAdminMetric(() => adminMetricsStore.unregisterInstance(clusterNodeId), "relay instance shutdown");
             await closeOwnedResources();
             started = false;
             startedUrl = "";