@getpaseo/server 0.1.2 → 0.1.4

package/dist/server/server/websocket-server.d.ts

@@ -5,20 +5,26 @@ import type { AgentStorage } from "./agent/agent-storage.js";
 import type { DownloadTokenStore } from "./file-download/token-store.js";
 import type { TerminalManager } from "../terminal/terminal-manager.js";
 import type pino from "pino";
-import { type WSOutboundMessage } from "./messages.js";
+import { type ServerCapabilities, type WSOutboundMessage } from "./messages.js";
 import type { AllowedHostsConfig } from "./allowed-hosts.js";
 import type { AgentProviderRuntimeSettingsMap } from "./agent/provider-launch-config.js";
 import type { SpeechToTextProvider, TextToSpeechProvider } from "./speech/speech-provider.js";
+import type { Resolvable } from "./speech/provider-resolver.js";
+import type { SpeechReadinessSnapshot } from "./speech/speech-runtime.js";
 import type { LocalSpeechModelId } from "./speech/providers/local/models.js";
 import type { VoiceCallerContext, VoiceMcpStdioConfig, VoiceSpeakHandler } from "./voice-types.js";
 export type AgentMcpTransportFactory = () => Promise<Transport>;
+export type ExternalSocketMetadata = {
+    transport: "relay";
+    externalSessionKey: string;
+};
 type WebSocketServerConfig = {
     allowedOrigins: Set<string>;
     allowedHosts?: AllowedHostsConfig;
 };
 type WebSocketLike = {
     readyState: number;
-    send: (data: string) => void;
+    send: (data: string | Uint8Array | ArrayBuffer) => void;
     close: (code?: number, reason?: string) => void;
     on: (event: "message" | "close" | "error", listener: (...args: any[]) => void) => void;
     once: (event: "close" | "error", listener: (...args: any[]) => void) => void;
@@ -30,6 +36,7 @@ export declare class VoiceAssistantWebSocketServer {
     private readonly logger;
     private readonly wss;
     private readonly sessions;
+    private readonly externalSessionsByKey;
     private clientIdCounter;
     private readonly serverId;
     private readonly agentManager;
@@ -47,33 +54,42 @@ export declare class VoiceAssistantWebSocketServer {
     private readonly voiceSpeakHandlers;
     private readonly voiceCallerContexts;
     private readonly agentProviderRuntimeSettings;
+    private serverCapabilities;
     constructor(server: HTTPServer, logger: pino.Logger, serverId: string, agentManager: AgentManager, agentStorage: AgentStorage, downloadTokenStore: DownloadTokenStore, paseoHome: string, createAgentMcpTransport: AgentMcpTransportFactory, wsConfig: WebSocketServerConfig, speech?: {
-        stt: SpeechToTextProvider | null;
-        tts: TextToSpeechProvider | null;
+        stt: Resolvable<SpeechToTextProvider | null>;
+        tts: Resolvable<TextToSpeechProvider | null>;
     }, terminalManager?: TerminalManager | null, voice?: {
         voiceAgentMcpStdio?: VoiceMcpStdioConfig | null;
         ensureVoiceMcpSocketForAgent?: (agentId: string) => Promise<string>;
         removeVoiceMcpSocketForAgent?: (agentId: string) => Promise<void>;
     }, dictation?: {
         finalTimeoutMs?: number;
-        stt?: SpeechToTextProvider | null;
+        stt?: Resolvable<SpeechToTextProvider | null>;
         localModels?: {
             modelsDir: string;
             defaultModelIds: LocalSpeechModelId[];
         };
+        getSpeechReadiness?: () => SpeechReadinessSnapshot;
     }, agentProviderRuntimeSettings?: AgentProviderRuntimeSettingsMap);
     broadcast(message: WSOutboundMessage): void;
-    attachExternalSocket(ws: WebSocketLike): Promise<void>;
+    publishSpeechReadiness(readiness: SpeechReadinessSnapshot | null): void;
+    updateServerCapabilities(capabilities: ServerCapabilities | null | undefined): void;
+    attachExternalSocket(ws: WebSocketLike, metadata?: ExternalSocketMetadata): Promise<void>;
     close(): Promise<void>;
     private sendToClient;
+    private sendBinaryToClient;
     private attachSocket;
+    private buildServerInfoStatusPayload;
+    private broadcastServerInfo;
+    private sendServerInfo;
+    private bindSocketHandlers;
     resolveVoiceSpeakHandler(callerAgentId: string): VoiceSpeakHandler | null;
     resolveVoiceCallerContext(callerAgentId: string): VoiceCallerContext | null;
     private detachSocket;
+    private cleanupConnection;
     private handleRawMessage;
     private readonly ACTIVITY_THRESHOLD_MS;
     private getClientActivityState;
-    private computeShouldNotifyForClient;
     private broadcastAgentAttention;
 }
 export {};

package/dist/server/server/websocket-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket-server.d.ts","sourceRoot":"","sources":["../../../src/server/websocket-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"websocket-server.d.ts","sourceRoot":"","sources":["../../../src/server/websocket-server.ts"],"names":[],"mappings":"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"}

package/dist/server/server/websocket-server.js

@@ -2,10 +2,60 @@ import { WebSocketServer } from "ws";
 import { join } from "path";
 import { hostname as getHostname } from "node:os";
 import { WSInboundMessageSchema, wrapSessionMessage, } from "./messages.js";
+import { asUint8Array, decodeBinaryMuxFrame, encodeBinaryMuxFrame, } from "../shared/binary-mux.js";
 import { isHostAllowed } from "./allowed-hosts.js";
 import { Session } from "./session.js";
 import { PushTokenStore } from "./push/token-store.js";
 import { PushService } from "./push/push-service.js";
+import { computeShouldNotifyClient, computeShouldSendPush, } from "./agent-attention-policy.js";
+function toServerCapabilityState(params) {
+    const { state, reason } = params;
+    return {
+        enabled: state.enabled,
+        reason,
+    };
+}
+function resolveCapabilityReason(params) {
+    const { state, readiness } = params;
+    if (state.available) {
+        return "";
+    }
+    if (readiness.voiceFeature.reasonCode === "model_download_in_progress") {
+        const baseMessage = readiness.voiceFeature.message.trim();
+        if (baseMessage.includes("Try again in a few minutes")) {
+            return baseMessage;
+        }
+        return `${baseMessage} Try again in a few minutes.`;
+    }
+    return state.message;
+}
+function buildServerCapabilities(params) {
+    const readiness = params.readiness;
+    if (!readiness) {
+        return undefined;
+    }
+    return {
+        voice: {
+            dictation: toServerCapabilityState({
+                state: readiness.dictation,
+                reason: resolveCapabilityReason({
+                    state: readiness.dictation,
+                    readiness,
+                }),
+            }),
+            voice: toServerCapabilityState({
+                state: readiness.realtimeVoice,
+                reason: resolveCapabilityReason({
+                    state: readiness.realtimeVoice,
+                    readiness,
+                }),
+            }),
+        },
+    };
+}
+function areServerCapabilitiesEqual(current, next) {
+    return JSON.stringify(current ?? null) === JSON.stringify(next ?? null);
+}
 function bufferFromWsData(data) {
     if (typeof data === "string")
         return Buffer.from(data, "utf8");
@@ -16,12 +66,14 @@ function bufferFromWsData(data) {
         return data;
     return Buffer.from(data);
 }
+const EXTERNAL_SESSION_DISCONNECT_GRACE_MS = 90000;
 /**
  * WebSocket server that only accepts sockets + parses/forwards messages to the session layer.
  */
 export class VoiceAssistantWebSocketServer {
     constructor(server, logger, serverId, agentManager, agentStorage, downloadTokenStore, paseoHome, createAgentMcpTransport, wsConfig, speech, terminalManager, voice, dictation, agentProviderRuntimeSettings) {
         this.sessions = new Map();
+        this.externalSessionsByKey = new Map();
         this.clientIdCounter = 0;
         this.voiceSpeakHandlers = new Map();
         this.voiceCallerContexts = new Map();
@@ -39,6 +91,9 @@ export class VoiceAssistantWebSocketServer {
         this.voice = voice ?? null;
         this.dictation = dictation ?? null;
         this.agentProviderRuntimeSettings = agentProviderRuntimeSettings;
+        this.serverCapabilities = buildServerCapabilities({
+            readiness: this.dictation?.getSpeechReadiness?.() ?? null,
+        });
         const pushLogger = this.logger.child({ module: "push" });
         this.pushTokenStore = new PushTokenStore(pushLogger, join(paseoHome, "push-tokens.json"));
         this.pushService = new PushService(pushLogger, this.pushTokenStore);
@@ -50,10 +105,11 @@ export class VoiceAssistantWebSocketServer {
             server,
             path: "/ws",
             verifyClient: ({ req }, callback) => {
-                const origin = req.headers.origin;
-                const requestHost = typeof req.headers.host === "string" ? req.headers.host : null;
+                const requestMetadata = extractSocketRequestMetadata(req);
+                const origin = requestMetadata.origin;
+                const requestHost = requestMetadata.host ?? null;
                 if (requestHost && !isHostAllowed(requestHost, allowedHosts)) {
-                    this.logger.warn({ host: requestHost }, "Rejected connection from disallowed host");
+                    this.logger.warn({ ...requestMetadata, host: requestHost }, "Rejected connection from disallowed host");
                     callback(false, 403, "Host not allowed");
                     return;
                 }
@@ -64,7 +120,7 @@ export class VoiceAssistantWebSocketServer {
                     callback(true);
                 }
                 else {
-                    this.logger.warn({ origin }, "Rejected connection from origin");
+                    this.logger.warn({ ...requestMetadata, origin }, "Rejected connection from origin");
                     callback(false, 403, "Origin not allowed");
                 }
             },
@@ -83,13 +139,33 @@ export class VoiceAssistantWebSocketServer {
             }
         }
     }
-    async attachExternalSocket(ws) {
-        await this.attachSocket(ws);
+    publishSpeechReadiness(readiness) {
+        this.updateServerCapabilities(buildServerCapabilities({ readiness }));
+    }
+    updateServerCapabilities(capabilities) {
+        const next = capabilities ?? undefined;
+        if (areServerCapabilitiesEqual(this.serverCapabilities, next)) {
+            return;
+        }
+        this.serverCapabilities = next;
+        this.broadcastServerInfo();
+    }
+    async attachExternalSocket(ws, metadata) {
+        await this.attachSocket(ws, undefined, metadata);
     }
     async close() {
+        const uniqueConnections = new Set([
+            ...this.sessions.values(),
+            ...this.externalSessionsByKey.values(),
+        ]);
         const cleanupPromises = [];
-        for (const [ws, session] of this.sessions) {
-            cleanupPromises.push(session.cleanup());
+        for (const connection of uniqueConnections) {
+            if (connection.externalDisconnectCleanupTimeout) {
+                clearTimeout(connection.externalDisconnectCleanupTimeout);
+                connection.externalDisconnectCleanupTimeout = null;
+            }
+            const ws = connection.socketRef.current;
+            cleanupPromises.push(connection.session.cleanup());
             cleanupPromises.push(new Promise((resolve) => {
                 // WebSocket.CLOSED = 3
                 if (ws.readyState === 3) {
@@ -102,6 +178,7 @@ export class VoiceAssistantWebSocketServer {
         }
         await Promise.all(cleanupPromises);
         this.sessions.clear();
+        this.externalSessionsByKey.clear();
         this.wss.close();
     }
     sendToClient(ws, message) {
@@ -110,13 +187,66 @@ export class VoiceAssistantWebSocketServer {
             ws.send(JSON.stringify(message));
         }
     }
-    async attachSocket(ws, _request) {
+    sendBinaryToClient(ws, frame) {
+        if (ws.readyState !== 1) {
+            return;
+        }
+        ws.send(encodeBinaryMuxFrame(frame));
+    }
+    async attachSocket(ws, request, metadata) {
+        const externalSessionKey = metadata?.transport === "relay" && metadata.externalSessionKey.trim().length > 0
+            ? metadata.externalSessionKey
+            : null;
+        if (externalSessionKey) {
+            const existing = this.externalSessionsByKey.get(externalSessionKey);
+            if (existing) {
+                if (existing.externalDisconnectCleanupTimeout) {
+                    clearTimeout(existing.externalDisconnectCleanupTimeout);
+                    existing.externalDisconnectCleanupTimeout = null;
+                }
+                const previousSocket = existing.socketRef.current;
+                if (previousSocket !== ws) {
+                    this.sessions.delete(previousSocket);
+                    existing.socketRef.current = ws;
+                }
+                this.sessions.set(ws, existing);
+                this.sendServerInfo(ws);
+                existing.connectionLogger.trace({
+                    clientId: existing.clientId,
+                    externalSessionKey,
+                    totalSessions: this.sessions.size,
+                }, "Client reconnected");
+                this.bindSocketHandlers(ws, existing);
+                return;
+            }
+        }
         const clientId = `client-${++this.clientIdCounter}`;
-        const connectionLogger = this.logger.child({ clientId });
+        const requestMetadata = extractSocketRequestMetadata(request);
+        const connectionLoggerFields = {
+            clientId,
+            transport: externalSessionKey ? "relay" : "direct",
+        };
+        if (requestMetadata.host) {
+            connectionLoggerFields.host = requestMetadata.host;
+        }
+        if (requestMetadata.origin) {
+            connectionLoggerFields.origin = requestMetadata.origin;
+        }
+        if (requestMetadata.userAgent) {
+            connectionLoggerFields.userAgent = requestMetadata.userAgent;
+        }
+        if (requestMetadata.remoteAddress) {
+            connectionLoggerFields.remoteAddress = requestMetadata.remoteAddress;
+        }
+        const connectionLogger = this.logger.child(connectionLoggerFields);
+        const socketRef = { current: ws };
         const session = new Session({
             clientId,
             onMessage: (msg) => {
-                this.sendToClient(ws, wrapSessionMessage(msg));
+                this.sendToClient(socketRef.current, wrapSessionMessage(msg));
+            },
+            onBinaryMessage: (frame) => {
+                this.sendBinaryToClient(socketRef.current, frame);
             },
             logger: connectionLogger.child({ module: "session" }),
             downloadTokenStore: this.downloadTokenStore,
@@ -148,27 +278,57 @@ export class VoiceAssistantWebSocketServer {
             dictation: this.dictation ?? undefined,
             agentProviderRuntimeSettings: this.agentProviderRuntimeSettings,
         });
-        this.sessions.set(ws, session);
+        const connection = {
+            session,
+            clientId,
+            connectionLogger,
+            socketRef,
+            externalSessionKey,
+            externalDisconnectCleanupTimeout: null,
+        };
+        this.sessions.set(ws, connection);
+        if (externalSessionKey) {
+            this.externalSessionsByKey.set(externalSessionKey, connection);
+        }
+        this.sendServerInfo(ws);
+        connectionLogger.trace({ clientId, externalSessionKey, totalSessions: this.sessions.size }, "Client connected");
+        this.bindSocketHandlers(ws, connection);
+    }
+    buildServerInfoStatusPayload() {
+        return {
+            status: "server_info",
+            serverId: this.serverId,
+            hostname: getHostname(),
+            ...(this.serverCapabilities ? { capabilities: this.serverCapabilities } : {}),
+        };
+    }
+    broadcastServerInfo() {
+        this.broadcast(wrapSessionMessage({
+            type: "status",
+            payload: this.buildServerInfoStatusPayload(),
+        }));
+    }
+    sendServerInfo(ws) {
         // Advertise stable server identity immediately on connect (used for URL/shareable IDs).
         this.sendToClient(ws, wrapSessionMessage({
             type: "status",
-            payload: {
-                status: "server_info",
-                serverId: this.serverId,
-                hostname: getHostname(),
-            },
+            payload: this.buildServerInfoStatusPayload(),
         }));
-        connectionLogger.info({ clientId, totalSessions: this.sessions.size }, "Client connected");
+    }
+    bindSocketHandlers(ws, connection) {
         ws.on("message", (data) => {
             void this.handleRawMessage(ws, data);
         });
-        ws.on("close", async () => {
-            await this.detachSocket(ws, connectionLogger, clientId);
+        ws.on("close", async (code, reason) => {
+            await this.detachSocket(ws, connection, {
+                code: typeof code === "number" ? code : undefined,
+                reason,
+            });
         });
         ws.on("error", async (error) => {
             const err = error instanceof Error ? error : new Error(String(error));
-            connectionLogger.error({ err }, "Client error");
-            await this.detachSocket(ws, connectionLogger, clientId);
+            connection.connectionLogger.error({ err }, "Client error");
+            await this.detachSocket(ws, connection, { error: err });
         });
     }
     resolveVoiceSpeakHandler(callerAgentId) {
@@ -177,17 +337,67 @@ export class VoiceAssistantWebSocketServer {
     resolveVoiceCallerContext(callerAgentId) {
         return this.voiceCallerContexts.get(callerAgentId) ?? null;
     }
-    async detachSocket(ws, connectionLogger, clientId) {
-        const session = this.sessions.get(ws);
-        if (!session)
+    async detachSocket(ws, connection, details) {
+        const activeConnection = this.sessions.get(ws);
+        if (activeConnection !== connection)
             return;
-        connectionLogger.info({ clientId, totalSessions: this.sessions.size - 1 }, "Client disconnected");
-        await session.cleanup();
         this.sessions.delete(ws);
+        if (connection.externalSessionKey &&
+            connection.socketRef.current === ws) {
+            if (connection.externalDisconnectCleanupTimeout) {
+                clearTimeout(connection.externalDisconnectCleanupTimeout);
+            }
+            const timeout = setTimeout(() => {
+                if (connection.externalDisconnectCleanupTimeout !== timeout) {
+                    return;
+                }
+                connection.externalDisconnectCleanupTimeout = null;
+                void this.cleanupConnection(connection, "Client disconnected (grace timeout)");
+            }, EXTERNAL_SESSION_DISCONNECT_GRACE_MS);
+            connection.externalDisconnectCleanupTimeout = timeout;
+            connection.connectionLogger.trace({
+                clientId: connection.clientId,
+                externalSessionKey: connection.externalSessionKey,
+                code: details.code,
+                reason: stringifyCloseReason(details.reason),
+                reconnectGraceMs: EXTERNAL_SESSION_DISCONNECT_GRACE_MS,
+            }, "Client disconnected; waiting for reconnect");
+            return;
+        }
+        await this.cleanupConnection(connection, "Client disconnected");
+    }
+    async cleanupConnection(connection, logMessage) {
+        if (connection.externalDisconnectCleanupTimeout) {
+            clearTimeout(connection.externalDisconnectCleanupTimeout);
+            connection.externalDisconnectCleanupTimeout = null;
+        }
+        const currentSocket = connection.socketRef.current;
+        this.sessions.delete(currentSocket);
+        if (connection.externalSessionKey) {
+            const existing = this.externalSessionsByKey.get(connection.externalSessionKey);
+            if (existing === connection) {
+                this.externalSessionsByKey.delete(connection.externalSessionKey);
+            }
+        }
+        connection.connectionLogger.trace({ clientId: connection.clientId, totalSessions: this.sessions.size }, logMessage);
+        await connection.session.cleanup();
     }
     async handleRawMessage(ws, data) {
         try {
+            const activeConnection = this.sessions.get(ws);
             const buffer = bufferFromWsData(data);
+            const asBytes = asUint8Array(buffer);
+            if (asBytes) {
+                const frame = decodeBinaryMuxFrame(asBytes);
+                if (frame) {
+                    if (!activeConnection) {
+                        this.logger.error("No session found for client");
+                        return;
+                    }
+                    activeConnection.session.handleBinaryFrame(frame);
+                    return;
+                }
+            }
             const parsed = JSON.parse(buffer.toString());
             const parsedMessage = WSInboundMessageSchema.safeParse(parsed);
             if (!parsedMessage.success) {
@@ -197,7 +407,9 @@ export class VoiceAssistantWebSocketServer {
                     parsed != null &&
                     "type" in parsed &&
                     parsed.type === "session";
-                this.logger.warn({
+                const log = activeConnection?.connectionLogger ?? this.logger;
+                log.warn({
+                    clientId: activeConnection?.clientId,
                     requestId: requestInfo?.requestId,
                     requestType: requestInfo?.requestType,
                     error: parsedMessage.error.message,
@@ -225,42 +437,19 @@ export class VoiceAssistantWebSocketServer {
                 return;
             }
             const message = parsedMessage.data;
-            const messageSummary = {
-                type: message.type,
-                ...(message.type === "session" && message.message
-                    ? { sessionMessageType: message.message.type }
-                    : {}),
-            };
-            const isSessionNoise = message.type === "session" &&
-                (message.message.type === "client_heartbeat" ||
-                    message.message.type === "voice_audio_chunk" ||
-                    message.message.type === "dictation_stream_chunk");
-            if (!isSessionNoise) {
-                this.logger.debug(messageSummary, "Received message");
-            }
             if (message.type === "ping") {
                 this.sendToClient(ws, { type: "pong" });
                 return;
             }
             if (message.type === "recording_state") {
-                this.logger.debug({ isRecording: message.isRecording }, "Recording state");
                 return;
             }
-            const session = this.sessions.get(ws);
-            if (!session) {
+            if (!activeConnection) {
                 this.logger.error("No session found for client");
                 return;
             }
             if (message.type === "session") {
-                if (message.message.type === "create_agent_request") {
-                    this.logger.debug({
-                        cwd: message.message.config.cwd,
-                        initialMode: message.message.config.modeId,
-                        worktreeName: message.message.worktreeName,
-                        requestId: message.message.requestId,
-                    }, "create_agent_request details");
-                }
-                await session.handleMessage(message.message);
+                await activeConnection.session.handleMessage(message.message);
             }
         }
         catch (error) {
@@ -311,20 +500,11 @@ export class VoiceAssistantWebSocketServer {
     getClientActivityState(session) {
         const activity = session.getClientActivity();
         if (!activity) {
-            this.logger.debug("getClientActivityState: no activity for session");
             return { deviceType: null, focusedAgentId: null, isStale: true, appVisible: false };
         }
         const now = Date.now();
         const ageMs = now - activity.lastActivityAt.getTime();
         const isStale = ageMs >= this.ACTIVITY_THRESHOLD_MS;
-        this.logger.debug({
-            deviceType: activity.deviceType,
-            focusedAgentId: activity.focusedAgentId,
-            lastActivityAt: activity.lastActivityAt.toISOString(),
-            ageMs,
-            isStale,
-            appVisible: activity.appVisible,
-        }, "getClientActivityState");
         return {
             deviceType: activity.deviceType,
             focusedAgentId: activity.focusedAgentId,
@@ -332,53 +512,21 @@ export class VoiceAssistantWebSocketServer {
             appVisible: activity.appVisible,
         };
     }
-    computeShouldNotifyForClient(clientState, allClientStates, agentId) {
-        const isAnyoneActiveOnAgent = allClientStates.some((state) => state.focusedAgentId === agentId && state.appVisible && !state.isStale);
-        if (isAnyoneActiveOnAgent) {
-            return false;
-        }
-        if (clientState.deviceType === null) {
-            return true;
-        }
-        if (!clientState.isStale && clientState.appVisible && clientState.focusedAgentId !== null) {
-            return true;
-        }
-        if (!clientState.isStale) {
-            return false;
-        }
-        const hasActiveWebClient = allClientStates.some((state) => state.deviceType === "web" && !state.isStale);
-        if (clientState.deviceType === "mobile") {
-            return !hasActiveWebClient;
-        }
-        if (clientState.deviceType === "web") {
-            const hasOtherClient = allClientStates.some((state) => state !== clientState && (state.deviceType === "mobile" || state.deviceType === null));
-            return !hasOtherClient;
-        }
-        return true;
-    }
     broadcastAgentAttention(params) {
         const clientEntries = [];
-        for (const [ws, session] of this.sessions) {
+        for (const [ws, connection] of this.sessions) {
             clientEntries.push({
                 ws,
-                state: this.getClientActivityState(session),
+                state: this.getClientActivityState(connection.session),
             });
         }
         const allStates = clientEntries.map((e) => e.state);
-        this.logger.debug({
-            agentId: params.agentId,
-            reason: params.reason,
-            clientCount: clientEntries.length,
-            allStates,
-        }, "broadcastAgentAttention");
-        const hasActiveWebClient = allStates.some((state) => state.deviceType === "web" && !state.isStale);
-        const hasActiveMobileForegroundClient = allStates.some((state) => state.deviceType === "mobile" && state.appVisible && !state.isStale);
-        // Push is only a fallback when the user is away from their desktop/web.
+        // Push is only a fallback when the user is away from desktop/web.
         // Also suppress push if they're actively using the mobile app.
-        const shouldSendPush = params.reason !== "error" &&
-            !hasActiveWebClient &&
-            !hasActiveMobileForegroundClient;
-        this.logger.debug({ hasActiveWebClient, hasActiveMobileForegroundClient, shouldSendPush }, "Push gating check");
+        const shouldSendPush = computeShouldSendPush({
+            reason: params.reason,
+            allClientStates: allStates,
+        });
         if (shouldSendPush) {
             const tokens = this.pushTokenStore.getAllTokens();
             this.logger.info({ tokenCount: tokens.length }, "Sending push notification");
@@ -401,7 +549,11 @@ export class VoiceAssistantWebSocketServer {
             }
         }
         for (const { ws, state } of clientEntries) {
-            const shouldNotify = this.computeShouldNotifyForClient(state, allStates, params.agentId);
+            const shouldNotify = computeShouldNotifyClient({
+                clientState: state,
+                allClientStates: allStates,
+                agentId: params.agentId,
+            });
             const message = wrapSessionMessage({
                 type: "agent_stream",
                 payload: {
@@ -420,6 +572,40 @@ export class VoiceAssistantWebSocketServer {
         }
     }
 }
+function extractSocketRequestMetadata(request) {
+    if (!request || typeof request !== "object") {
+        return {};
+    }
+    const record = request;
+    const host = typeof record.headers?.host === "string" ? record.headers.host : undefined;
+    const origin = typeof record.headers?.origin === "string" ? record.headers.origin : undefined;
+    const userAgent = typeof record.headers?.["user-agent"] === "string"
+        ? record.headers["user-agent"]
+        : undefined;
+    const remoteAddress = typeof record.socket?.remoteAddress === "string"
+        ? record.socket.remoteAddress
+        : undefined;
+    return {
+        ...(host ? { host } : {}),
+        ...(origin ? { origin } : {}),
+        ...(userAgent ? { userAgent } : {}),
+        ...(remoteAddress ? { remoteAddress } : {}),
+    };
+}
+function stringifyCloseReason(reason) {
+    if (typeof reason === "string") {
+        return reason.length > 0 ? reason : null;
+    }
+    if (Buffer.isBuffer(reason)) {
+        const text = reason.toString();
+        return text.length > 0 ? text : null;
+    }
+    if (reason == null) {
+        return null;
+    }
+    const text = String(reason);
+    return text.length > 0 ? text : null;
+}
 function extractRequestInfoFromUnknownWsInbound(payload) {
     if (!payload || typeof payload !== "object") {
         return null;