ocuclaw 0.1.0

package/dist/runtime/downstream-server.js

@@ -0,0 +1,1565 @@
+import * as WebSocketModule from "ws";
+
+// `ws` exposes different server entrypoints across ESM/CJS consumers.
+const WebSocket =
+  WebSocketModule.default || WebSocketModule.WebSocket || WebSocketModule;
+const WebSocketServer =
+  WebSocketModule.WebSocketServer || WebSocketModule.Server || WebSocket.Server;
+
+function normalizeLogger(logger) {
+  if (!logger || typeof logger !== "object") {
+    return console;
+  }
+  return {
+    info: typeof logger.info === "function" ? logger.info.bind(logger) : console.log,
+    warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn,
+    error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error,
+    debug:
+      typeof logger.debug === "function" ? logger.debug.bind(logger) : console.debug,
+  };
+}
+
+// --- Factory ---
+
+/**
+ * Create a downstream WebSocket server.
+ *
+ * Manages WebSocket transport for downstream clients (Even App,
+ * commander.html). Handles token-based authentication, client tracking,
+ * and message delegation to the downstream handler.
+ *
+ * @param {object} opts
+ * @param {object} opts.handler
+ *   Downstream handler instance (from createDownstreamHandler).
+ * @param {() => string|null} opts.getCurrentPages
+ *   Returns formatted pages JSON string, or null if no pages yet.
+ * @param {() => string|null} opts.getCurrentStatus
+ *   Returns formatted status JSON string, or null if no status yet.
+ * @param {() => string|null} [opts.getCurrentDebugConfig]
+ *   Returns formatted debug-config snapshot JSON string for app/WebUI clients.
+ * @param {() => {pagesRevision?: number, statusRevision?: number}|null} [opts.getCurrentResumeState]
+ *   Returns current server-side resume revisions for pages/status.
+ * @param {number} opts.port
+ *   WebSocket server port (0 for OS-assigned).
+ * @param {string} opts.host
+ *   WebSocket server bind address.
+ * @param {string} opts.token
+ *   Expected authentication token.
+ * @param {(meta: object) => void} [opts.onClientConnected]
+ *   Optional callback for client connection events.
+ * @param {(meta: object) => void} [opts.onClientDisconnected]
+ *   Optional callback for client disconnection events.
+ * @param {(meta: object) => void} [opts.onTransportControl]
+ *   Optional callback for transport control frames handled before app message routing.
+ * @returns {object} Server instance with broadcast, unicast, getClientIds, close.
+ */
+function createDownstreamServer(opts) {
+  const logger = normalizeLogger(opts.logger);
+  const handler = opts.handler;
+  const getCurrentPages = opts.getCurrentPages;
+  const getCurrentStatus = opts.getCurrentStatus;
+  const getCurrentDebugConfig = opts.getCurrentDebugConfig || null;
+  const getCurrentResumeState = opts.getCurrentResumeState || null;
+  const token = opts.token;
+  const onClientConnected = opts.onClientConnected || null;
+  const onClientDisconnected = opts.onClientDisconnected || null;
+  const onTransportControl = opts.onTransportControl || null;
+  const protocolHelloTimeoutMs = Number.isFinite(opts.protocolHelloTimeoutMs)
+    ? Math.max(0, Math.floor(opts.protocolHelloTimeoutMs))
+    : 120;
+  const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
+  const resumeHandshakeTimeoutMs = Number.isFinite(opts.resumeHandshakeTimeoutMs)
+    ? Math.max(0, Math.floor(opts.resumeHandshakeTimeoutMs))
+    : 120;
+  const nudgeActiveIntervalMs = Number.isFinite(opts.nudgeActiveIntervalMs)
+    ? Math.max(1, Math.floor(opts.nudgeActiveIntervalMs))
+    : 150;
+  const nudgeSlowIntervalMs = Number.isFinite(opts.nudgeSlowIntervalMs)
+    ? Math.max(1, Math.floor(opts.nudgeSlowIntervalMs))
+    : 1000;
+  const nudgeIdleDeactivateMs = Number.isFinite(opts.nudgeIdleDeactivateMs)
+    ? Math.max(0, Math.floor(opts.nudgeIdleDeactivateMs))
+    : 5000;
+  const nudgeHeartbeatIntervalMs = Number.isFinite(opts.nudgeHeartbeatIntervalMs)
+    ? Math.max(1, Math.floor(opts.nudgeHeartbeatIntervalMs))
+    : 10000;
+  const nudgeHardTimeoutMs = Number.isFinite(opts.nudgeHardTimeoutMs)
+    ? Math.max(1, Math.floor(opts.nudgeHardTimeoutMs))
+    : 60000;
+  const nudgeStaleHeartbeatThresholdMs = nudgeHeartbeatIntervalMs * 2;
+  const RENDER_NUDGE_FRAME = JSON.stringify({ type: "render_nudge" });
+
+  /** @type {Map<string, WebSocket>} */
+  const clients = new Map();
+  /** @type {Map<string, {selectedVersion: "v2"|null, supportedProtocolVersions: string[], clientName: string|null, clientVersion: string|null, sessionKey: string|null, reason: string|null}>} */
+  const protocolState = new Map();
+  /** @type {Map<string, {pagesSynced: boolean, statusSynced: boolean, approvalsSynced: boolean, debugConfigSynced: boolean, resumeReceived: boolean, timer: any}>} */
+  const syncState = new Map();
+  /** @type {Map<string, {visibilityState: "hidden"|"visible"|"blurred"|null, streamChars: number|null, lastHeartbeatAtMs: number|null, lastRelayStreamingActivityAtMs: number|null, interactionStage: "idle"|"listening"|"voice_handoff"|"thinking"|"streaming"|"post_turn_drain", cadenceBucket: "idle"|"active_non_stream"|"active_stream", nudgeActive: boolean, nudgeIntervalMs: number|null, nudgeStartedAtMs: number|null, lastNudgeAtMs: number|null, stalledHeartbeatCount: number, nudgeTimer: any, idleDeactivateTimer: any, staleHeartbeatTimer: any, hardTimeoutTimer: any}>} */
+  const clientNudgeState = new Map();
+  /** @type {Map<string, string>} */
+  const unresolvedApprovals = new Map();
+  let nextClientId = 1;
+  const APP_PROTOCOL = {
+    approvalRequest: "ocuclaw.approval.request",
+    approvalResolved: "ocuclaw.approval.resolved",
+    debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
+    pages: "ocuclaw.view.pages.snapshot",
+    resume: "ocuclaw.sync.resume",
+    resumeAck: "ocuclaw.sync.resume.ack",
+    status: "ocuclaw.runtime.status",
+  };
+  const REMOVED_V1_APP_TYPES = new Set([
+    "approvalResponse",
+    "eventDebug",
+    "getEvenAiSettings",
+    "getOcuClawSettings",
+    "getModelsCatalog",
+    "getSkills",
+    "getSessionModelConfig",
+    "getSessions",
+    "newChat",
+    "newSession",
+    "resume",
+    "send",
+    "setEvenAiSettings",
+    "setOcuClawSettings",
+    "setSessionModelConfig",
+    "slashCommand",
+    "subscribeProtocol",
+    "switchSession",
+  ]);
+
+  function truncateForLog(value, maxChars = 120) {
+    if (typeof value !== "string") return "";
+    if (value.length <= maxChars) return value;
+    return `${value.slice(0, maxChars)}...`;
+  }
+
+  function updateClientRole(meta, messageType, clientKind = "unknown") {
+    if (!meta || typeof messageType !== "string") return;
+    if (!meta.firstMessageType) meta.firstMessageType = messageType;
+
+    if (clientKind === "debug") {
+      meta.role = "debug";
+      return;
+    }
+    if (meta.role === "debug") {
+      return;
+    }
+
+    const nextRole =
+      messageType === "remote-control" ? "control" : "app";
+    if (meta.role === "unknown") {
+      meta.role = nextRole;
+      return;
+    }
+    if (meta.role !== nextRole) {
+      meta.role = "mixed";
+    }
+  }
+
+  function parseRevision(value) {
+    if (!Number.isFinite(Number(value))) return null;
+    const num = Math.floor(Number(value));
+    if (num < 0) return null;
+    return num;
+  }
+
+  function parseBool(value) {
+    if (value === true || value === false) return value;
+    if (typeof value === "number") return value !== 0;
+    if (typeof value !== "string") return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized === "true" || normalized === "1" || normalized === "yes";
+  }
+
+  function parseOptionalTrimmedString(value) {
+    if (typeof value !== "string") return null;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+  }
+
+  function parseVisibilityState(value) {
+    const normalized = parseOptionalTrimmedString(value);
+    if (!normalized) return null;
+    const lowered = normalized.toLowerCase();
+    return lowered === "hidden" || lowered === "visible" || lowered === "blurred"
+      ? lowered
+      : null;
+  }
+
+  function parseVisibilityControl(value) {
+    if (!value || value.type !== "visibility") {
+      return null;
+    }
+    const state = parseVisibilityState(value.state);
+    if (!state) {
+      return null;
+    }
+    return { type: "visibility", state };
+  }
+
+  function parseOptionalNonNegativeInt(value) {
+    if (value === null || value === undefined) return null;
+    if (!Number.isFinite(Number(value))) return null;
+    const num = Math.floor(Number(value));
+    return num >= 0 ? num : null;
+  }
+
+  function parseDrainCompleteControl(value) {
+    if (!value || value.type !== "drain_complete") {
+      return null;
+    }
+    return { type: "drain_complete" };
+  }
+
+  function parseEnrichedPing(value) {
+    if (!value || value.type !== "ping") {
+      return null;
+    }
+    return {
+      type: "ping",
+      ts: Number.isFinite(Number(value.ts)) ? Number(value.ts) : null,
+      streamChars: parseOptionalNonNegativeInt(value.streamChars),
+      visibilityState: parseVisibilityState(value.visibilityState),
+    };
+  }
+
+  function normalizeProtocolVersion(value) {
+    const normalized = parseOptionalTrimmedString(value);
+    if (!normalized) return null;
+    const lowered = normalized.toLowerCase();
+    return lowered === "v1" || lowered === "v2" ? lowered : null;
+  }
+
+  function parseSupportedProtocolVersions(value) {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+    const versions = [];
+    for (const entry of value) {
+      const version = normalizeProtocolVersion(entry);
+      if (version && !versions.includes(version)) {
+        versions.push(version);
+      }
+    }
+    return versions;
+  }
+
+  function parseProtocolHello(value) {
+    if (!value || value.type !== "protocolHello") {
+      return null;
+    }
+    return {
+      supportedProtocolVersions: parseSupportedProtocolVersions(
+        value.supportedProtocolVersions || value.supportedVersions,
+      ),
+      preferredProtocolVersion:
+        normalizeProtocolVersion(value.preferredProtocolVersion) || "v2",
+      clientName:
+        parseOptionalTrimmedString(value.clientName) ||
+        parseOptionalTrimmedString(value.clientId),
+      clientVersion: parseOptionalTrimmedString(value.clientVersion),
+      sessionKey: parseOptionalTrimmedString(value.sessionKey),
+    };
+  }
+
+  function describeProtocolClient(state) {
+    if (!state) return "unknown";
+    const clientName = parseOptionalTrimmedString(state.clientName);
+    const clientVersion = parseOptionalTrimmedString(state.clientVersion);
+    if (clientName && clientVersion) {
+      return `${clientName}/${clientVersion}`;
+    }
+    return clientName || "unknown";
+  }
+
+  function classifyClientKindFromName(clientName) {
+    const normalizedName = parseOptionalTrimmedString(clientName);
+    if (!normalizedName) return "unknown";
+    const normalized = normalizedName.toLowerCase();
+    if (normalized === "debugctl") {
+      return "debug";
+    }
+    return "app";
+  }
+
+  function classifyClientKind(state) {
+    if (!state) return "unknown";
+    const clientName = parseOptionalTrimmedString(state.clientName);
+    if (!clientName) return "unknown";
+    return classifyClientKindFromName(clientName);
+  }
+
+  function countConnectedAppClients(excludeClientId = null) {
+    let count = 0;
+    for (const [clientId, ws] of clients) {
+      if (excludeClientId && clientId === excludeClientId) {
+        continue;
+      }
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        continue;
+      }
+      if (classifyClientKind(protocolState.get(clientId)) !== "app") {
+        continue;
+      }
+      count += 1;
+    }
+    return count;
+  }
+
+  function isAppClient(clientId) {
+    return classifyClientKind(protocolState.get(clientId)) === "app";
+  }
+
+  function closeConnectedAppClients(opts = {}) {
+    const excludeClientId = parseOptionalTrimmedString(opts.excludeClientId);
+    const requestedReason = parseOptionalTrimmedString(opts.reason);
+    const reason = requestedReason || "debug_injected_transport_loss";
+    const closedClientIds = [];
+    for (const [clientId, ws] of clients) {
+      if (excludeClientId && clientId === excludeClientId) {
+        continue;
+      }
+      if (!isAppClient(clientId)) {
+        continue;
+      }
+      if (
+        !ws ||
+        (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING)
+      ) {
+        continue;
+      }
+      const protocol = protocolState.get(clientId);
+      logger.warn(
+        `[downstream] ${clientId} debug injected transport loss reason="${reason}" client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
+      );
+      if (typeof ws.terminate === "function") {
+        ws.terminate();
+      } else {
+        ws.close(1012, reason);
+      }
+      closedClientIds.push(clientId);
+    }
+    return {
+      closedCount: closedClientIds.length,
+      closedClientIds,
+      reason,
+    };
+  }
+
+  function interactionStageBucket(stage) {
+    switch (stage) {
+      case "listening":
+      case "voice_handoff":
+      case "thinking":
+        return "active_non_stream";
+      case "streaming":
+      case "post_turn_drain":
+        return "active_stream";
+      default:
+        return "idle";
+    }
+  }
+
+  function formatProtocolHelloAck(payload) {
+    return JSON.stringify({
+      type: "protocolHelloAck",
+      protocolVersion: payload.protocolVersion,
+      supportedProtocolVersions: payload.supportedProtocolVersions || ["v2"],
+      reason: payload.reason || null,
+      deprecatedV1: false,
+    });
+  }
+
+  function ensureProtocolState(clientId) {
+    let state = protocolState.get(clientId);
+    if (!state) {
+      state = {
+        selectedVersion: null,
+        supportedProtocolVersions: ["v2"],
+        clientName: null,
+        clientVersion: null,
+        sessionKey: null,
+        reason: null,
+      };
+      protocolState.set(clientId, state);
+    }
+    return state;
+  }
+
+  function createClientNudgeState() {
+    return {
+      visibilityState: null,
+      streamChars: null,
+      lastHeartbeatAtMs: null,
+      lastRelayStreamingActivityAtMs: null,
+      interactionStage: "idle",
+      cadenceBucket: "idle",
+      nudgeActive: false,
+      nudgeIntervalMs: null,
+      nudgeStartedAtMs: null,
+      lastNudgeAtMs: null,
+      stalledHeartbeatCount: 0,
+      nudgeTimer: null,
+      idleDeactivateTimer: null,
+      staleHeartbeatTimer: null,
+      hardTimeoutTimer: null,
+    };
+  }
+
+  function ensureClientNudgeState(clientId) {
+    let state = clientNudgeState.get(clientId);
+    if (!state) {
+      state = createClientNudgeState();
+      clientNudgeState.set(clientId, state);
+    }
+    return state;
+  }
+
+  function cloneClientNudgeState(state) {
+    if (!state) return null;
+    return {
+      visibilityState: state.visibilityState || null,
+      streamChars: Number.isFinite(state.streamChars) ? state.streamChars : null,
+      lastHeartbeatAtMs: Number.isFinite(state.lastHeartbeatAtMs)
+        ? state.lastHeartbeatAtMs
+        : null,
+      lastRelayStreamingActivityAtMs: Number.isFinite(
+        state.lastRelayStreamingActivityAtMs,
+      )
+        ? state.lastRelayStreamingActivityAtMs
+        : null,
+      interactionStage: state.interactionStage || "idle",
+      cadenceBucket: state.cadenceBucket || "idle",
+      nudgeActive: !!state.nudgeActive,
+      nudgeIntervalMs: Number.isFinite(state.nudgeIntervalMs)
+        ? state.nudgeIntervalMs
+        : null,
+      nudgeStartedAtMs: Number.isFinite(state.nudgeStartedAtMs)
+        ? state.nudgeStartedAtMs
+        : null,
+      lastNudgeAtMs: Number.isFinite(state.lastNudgeAtMs)
+        ? state.lastNudgeAtMs
+        : null,
+      stalledHeartbeatCount: Number.isFinite(state.stalledHeartbeatCount)
+        ? state.stalledHeartbeatCount
+        : 0,
+    };
+  }
+
+  function clearClientNudgeTimer(state, key, clearFn = clearTimeout) {
+    if (!state || !state[key]) return;
+    clearFn(state[key]);
+    state[key] = null;
+  }
+
+  function clearClientNudgeTimers(clientId) {
+    const state = clientNudgeState.get(clientId);
+    if (!state) return;
+    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
+    clearClientNudgeTimer(state, "idleDeactivateTimer");
+    clearClientNudgeTimer(state, "staleHeartbeatTimer");
+    clearClientNudgeTimer(state, "hardTimeoutTimer");
+  }
+
+  function isStreamingBroadcastType(messageType) {
+    return (
+      messageType === "streaming" ||
+      messageType === "ocuclaw.message.stream.delta"
+    );
+  }
+
+  function isPagesBroadcastType(messageType) {
+    return messageType === "pages" || messageType === APP_PROTOCOL.pages;
+  }
+
+  function isActivityBroadcastType(messageType) {
+    return messageType === "activity" || messageType === "ocuclaw.activity.update";
+  }
+
+  function isListenCommittedBroadcastType(messageType) {
+    return messageType === "listen-committed";
+  }
+
+  function isListenEndedBroadcastType(messageType) {
+    return messageType === "listen-ended";
+  }
+
+  function resetClientStallTracking(state) {
+    if (!state) return;
+    state.stalledHeartbeatCount = 0;
+  }
+
+  function hasStaleHeartbeat(state, now = Date.now()) {
+    if (!state || !Number.isFinite(state.lastHeartbeatAtMs)) {
+      return false;
+    }
+    return now - state.lastHeartbeatAtMs >= nudgeStaleHeartbeatThresholdMs;
+  }
+
+  function isVisibilityDegraded(state) {
+    return (
+      !!state &&
+      (state.visibilityState === "hidden" || state.visibilityState === "blurred")
+    );
+  }
+
+  function sendRenderNudge(clientId) {
+    const ws = clients.get(clientId);
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      stopClientNudges(clientId, "socket_unavailable");
+      return;
+    }
+    sendMessageToClient(clientId, ws, RENDER_NUDGE_FRAME);
+    ensureClientNudgeState(clientId).lastNudgeAtMs = Date.now();
+  }
+
+  function scheduleClientHardTimeout(clientId) {
+    const state = clientNudgeState.get(clientId);
+    if (!state) return;
+    clearClientNudgeTimer(state, "hardTimeoutTimer");
+    if (!state.nudgeActive) return;
+    state.hardTimeoutTimer = setTimeout(() => {
+      state.hardTimeoutTimer = null;
+      setClientInteractionStage(clientId, "idle", {
+        reason: "nudge_hard_timeout",
+        deactivateImmediately: true,
+      });
+    }, nudgeHardTimeoutMs);
+  }
+
+  function startClientNudges(
+    clientId,
+    intervalMs,
+    reason = "nudge_start",
+    sendImmediately = false,
+  ) {
+    if (!isAppClient(clientId)) return;
+    const ws = clients.get(clientId);
+    if (!ws || ws.readyState !== WebSocket.OPEN) return;
+    const state = ensureClientNudgeState(clientId);
+    const nextIntervalMs = Math.max(1, Math.floor(intervalMs));
+    const wasActive = !!state.nudgeActive;
+    const intervalChanged = state.nudgeIntervalMs !== nextIntervalMs;
+    state.cadenceBucket = interactionStageBucket(state.interactionStage);
+    if (!wasActive) {
+      state.nudgeActive = true;
+      state.nudgeStartedAtMs = Date.now();
+    }
+    if (wasActive && !intervalChanged) {
+      return;
+    }
+    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
+    state.nudgeActive = true;
+    state.nudgeIntervalMs = nextIntervalMs;
+    state.nudgeTimer = setInterval(() => {
+      sendRenderNudge(clientId);
+    }, nextIntervalMs);
+    if (!wasActive) {
+      scheduleClientHardTimeout(clientId);
+      if (sendImmediately) {
+        sendRenderNudge(clientId);
+      }
+    }
+  }
+
+  function stopClientNudges(clientId, _reason = "nudge_stop") {
+    const state = clientNudgeState.get(clientId);
+    if (!state) return;
+    clearClientNudgeTimer(state, "nudgeTimer", clearInterval);
+    clearClientNudgeTimer(state, "idleDeactivateTimer");
+    clearClientNudgeTimer(state, "hardTimeoutTimer");
+    state.nudgeActive = false;
+    state.nudgeIntervalMs = null;
+    state.nudgeStartedAtMs = null;
+    resetClientStallTracking(state);
+    scheduleClientStaleHeartbeatCheck(clientId);
+  }
+
+  function scheduleClientIdleDeactivation(clientId) {
+    const state = clientNudgeState.get(clientId);
+    if (!state) return;
+    clearClientNudgeTimer(state, "idleDeactivateTimer");
+    if (!state.nudgeActive || state.interactionStage !== "idle") {
+      return;
+    }
+    state.idleDeactivateTimer = setTimeout(() => {
+      state.idleDeactivateTimer = null;
+      const currentState = clientNudgeState.get(clientId);
+      if (!currentState || currentState.interactionStage !== "idle") {
+        return;
+      }
+      stopClientNudges(clientId, "idle_grace_elapsed");
+    }, nudgeIdleDeactivateMs);
+  }
+
+  function scheduleClientStaleHeartbeatCheck(clientId) {
+    const state = clientNudgeState.get(clientId);
+    if (!state) return;
+    clearClientNudgeTimer(state, "staleHeartbeatTimer");
+    if (
+      state.nudgeActive ||
+      interactionStageBucket(state.interactionStage) === "idle" ||
+      !Number.isFinite(state.lastHeartbeatAtMs)
+    ) {
+      return;
+    }
+    const delayMs = Math.max(
+      0,
+      (state.lastHeartbeatAtMs + nudgeStaleHeartbeatThresholdMs) - Date.now(),
+    );
+    state.staleHeartbeatTimer = setTimeout(() => {
+      state.staleHeartbeatTimer = null;
+      const currentState = clientNudgeState.get(clientId);
+      if (
+        !currentState ||
+        currentState.nudgeActive ||
+        interactionStageBucket(currentState.interactionStage) === "idle"
+      ) {
+        return;
+      }
+      if (!hasStaleHeartbeat(currentState)) {
+        scheduleClientStaleHeartbeatCheck(clientId);
+        return;
+      }
+      startClientNudges(
+        clientId,
+        nudgeActiveIntervalMs,
+        "stale_heartbeat_fallback",
+        true,
+      );
+    }, delayMs);
+  }
+
+  function maybeActivateClientNudges(clientId, reason = "nudge_eval") {
+    const state = clientNudgeState.get(clientId);
+    if (!state || !isAppClient(clientId)) return;
+    state.cadenceBucket = interactionStageBucket(state.interactionStage);
+    if (state.cadenceBucket === "idle") {
+      clearClientNudgeTimer(state, "staleHeartbeatTimer");
+      return;
+    }
+    if (state.nudgeActive) {
+      return;
+    }
+    if (isVisibilityDegraded(state) || hasStaleHeartbeat(state)) {
+      startClientNudges(clientId, nudgeActiveIntervalMs, reason, true);
+      return;
+    }
+    scheduleClientStaleHeartbeatCheck(clientId);
+  }
+
+  function setClientInteractionStage(clientId, nextStage, options = {}) {
+    if (!isAppClient(clientId)) return;
+    const state = ensureClientNudgeState(clientId);
+    const reason = options.reason || "interaction_stage";
+    const deactivateImmediately = options.deactivateImmediately === true;
+    state.interactionStage = nextStage;
+    state.cadenceBucket = interactionStageBucket(nextStage);
+    if (state.cadenceBucket !== "active_stream") {
+      resetClientStallTracking(state);
+    }
+    if (state.cadenceBucket === "idle") {
+      clearClientNudgeTimer(state, "staleHeartbeatTimer");
+      if (deactivateImmediately) {
+        stopClientNudges(clientId, reason);
+      } else {
+        scheduleClientIdleDeactivation(clientId);
+      }
+      return;
+    }
+    clearClientNudgeTimer(state, "idleDeactivateTimer");
+    if (
+      state.cadenceBucket === "active_non_stream" &&
+      state.nudgeActive &&
+      state.nudgeIntervalMs !== nudgeActiveIntervalMs
+    ) {
+      startClientNudges(clientId, nudgeActiveIntervalMs, reason, false);
+    }
+    maybeActivateClientNudges(clientId, reason);
+  }
+
+  function observeRelayStreamingActivity(clientId, atMs) {
+    if (!isAppClient(clientId)) return;
+    const state = ensureClientNudgeState(clientId);
+    state.lastRelayStreamingActivityAtMs = atMs;
+    resetClientStallTracking(state);
+    if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
+      startClientNudges(clientId, nudgeActiveIntervalMs, "relay_stream_progress");
+      return;
+    }
+    maybeActivateClientNudges(clientId, "relay_stream_activity");
+  }
+
+  function updateClientNudgeHeartbeat(clientId, ping) {
+    const state = ensureClientNudgeState(clientId);
+    const previousHeartbeatAtMs = Number.isFinite(state.lastHeartbeatAtMs)
+      ? state.lastHeartbeatAtMs
+      : null;
+    const previousStreamChars = Number.isFinite(state.streamChars)
+      ? state.streamChars
+      : null;
+    const nextStreamChars = Number.isFinite(ping.streamChars) ? ping.streamChars : null;
+    const streamAdvanced =
+      nextStreamChars !== null &&
+      (previousStreamChars === null || nextStreamChars > previousStreamChars);
+    const relayStreamAdvanced =
+      previousHeartbeatAtMs !== null &&
+      Number.isFinite(state.lastRelayStreamingActivityAtMs) &&
+      state.lastRelayStreamingActivityAtMs > previousHeartbeatAtMs;
+    state.streamChars = nextStreamChars;
+    if (ping.visibilityState) {
+      state.visibilityState = ping.visibilityState;
+    }
+    state.lastHeartbeatAtMs = Date.now();
+    state.cadenceBucket = interactionStageBucket(state.interactionStage);
+    if (state.visibilityState === "visible") {
+      stopClientNudges(clientId, "heartbeat_visible");
+    }
+    if (state.cadenceBucket === "active_stream") {
+      if (streamAdvanced || relayStreamAdvanced) {
+        resetClientStallTracking(state);
+        if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
+          startClientNudges(
+            clientId,
+            nudgeActiveIntervalMs,
+            streamAdvanced
+              ? "heartbeat_stream_progress"
+              : "relay_stream_progress",
+            false,
+          );
+        }
+      } else if (state.nudgeActive) {
+        state.stalledHeartbeatCount += 1;
+        if (
+          state.stalledHeartbeatCount >= 3 &&
+          state.nudgeIntervalMs !== nudgeSlowIntervalMs
+        ) {
+          startClientNudges(
+            clientId,
+            nudgeSlowIntervalMs,
+            "stream_stalled_decelerated",
+            false,
+          );
+        }
+      }
+    } else {
+      resetClientStallTracking(state);
+      if (state.nudgeActive && state.nudgeIntervalMs !== nudgeActiveIntervalMs) {
+        startClientNudges(clientId, nudgeActiveIntervalMs, "non_stream_fast", false);
+      }
+    }
+    maybeActivateClientNudges(clientId, "heartbeat_update");
+  }
+
+  function updateClientVisibilityState(clientId, visibilityState) {
+    const state = ensureClientNudgeState(clientId);
+    state.visibilityState = visibilityState;
+    if (visibilityState === "visible") {
+      stopClientNudges(clientId, "visibility_visible");
+      return;
+    }
+    maybeActivateClientNudges(clientId, "visibility_hidden");
+  }
+
+  function applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs) {
+    for (const [clientId] of clients) {
+      if (!isAppClient(clientId)) {
+        continue;
+      }
+      if (relayStreamingActivityAtMs !== null) {
+        setClientInteractionStage(clientId, "streaming", {
+          reason: "relay_streaming",
+        });
+        observeRelayStreamingActivity(clientId, relayStreamingActivityAtMs);
+        continue;
+      }
+      if (isListenCommittedBroadcastType(messageType)) {
+        setClientInteractionStage(clientId, "voice_handoff", {
+          reason: "listen_committed",
+        });
+        continue;
+      }
+      if (isListenEndedBroadcastType(messageType)) {
+        setClientInteractionStage(clientId, "idle", {
+          reason: "listen_ended",
+          deactivateImmediately: true,
+        });
+        continue;
+      }
+      if (isActivityBroadcastType(messageType)) {
+        const activityState = parseOptionalTrimmedString(parsed && parsed.state);
+        const normalizedActivity = activityState ? activityState.toLowerCase() : null;
+        const currentStage = ensureClientNudgeState(clientId).interactionStage;
+        if (normalizedActivity === "thinking") {
+          setClientInteractionStage(clientId, "thinking", {
+            reason: "activity_thinking",
+          });
+        } else if (normalizedActivity === "idle") {
+          if (currentStage === "streaming" || currentStage === "post_turn_drain") {
+            setClientInteractionStage(clientId, "post_turn_drain", {
+              reason: "activity_idle_stream_drain",
+            });
+          } else {
+            setClientInteractionStage(clientId, "idle", {
+              reason: "activity_idle",
+            });
+          }
+        }
+        continue;
+      }
+      if (isPagesBroadcastType(messageType)) {
+        const currentState = ensureClientNudgeState(clientId);
+        if (interactionStageBucket(currentState.interactionStage) !== "idle") {
+          setClientInteractionStage(clientId, "post_turn_drain", {
+            reason: "pages_snapshot",
+          });
+        }
+      }
+    }
+  }
+
+  function updateProtocolSessionKey(clientId, value) {
+    const sessionKey = parseOptionalTrimmedString(value);
+    if (!sessionKey) return;
+    ensureProtocolState(clientId).sessionKey = sessionKey;
+  }
+
+  function updateProtocolState(clientId, overrides = {}) {
+    const state = ensureProtocolState(clientId);
+    if (overrides.supportedProtocolVersions) {
+      state.supportedProtocolVersions = parseSupportedProtocolVersions(
+        overrides.supportedProtocolVersions,
+      );
+    }
+    if (overrides.clientName) {
+      state.clientName = parseOptionalTrimmedString(overrides.clientName);
+    }
+    if (overrides.clientVersion) {
+      state.clientVersion = parseOptionalTrimmedString(overrides.clientVersion);
+    }
+    if (overrides.sessionKey) {
+      state.sessionKey = parseOptionalTrimmedString(overrides.sessionKey);
+    }
+    if (overrides.selectedVersion !== undefined) {
+      state.selectedVersion = overrides.selectedVersion;
+    }
+    if (overrides.reason !== undefined) {
+      state.reason = overrides.reason || null;
+    }
+    return state;
+  }
+
+  function clearSyncTimer(clientId) {
+    const sync = syncState.get(clientId);
+    if (sync && sync.timer) {
+      clearTimeout(sync.timer);
+      sync.timer = null;
+    }
+  }
+
+  function closeForProtocolViolation(clientId, ws, reason, overrides = {}) {
+    updateProtocolState(clientId, { ...overrides, reason });
+    clearSyncTimer(clientId);
+    if (
+      ws &&
+      (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING)
+    ) {
+      ws.close(1008, reason);
+    }
+  }
+
+  function armResumeHandshakeTimeout(clientId, ws) {
+    const sync = syncState.get(clientId);
+    if (!sync) return;
+    clearSyncTimer(clientId);
+    sync.timer = setTimeout(() => {
+      sync.timer = null;
+      syncSnapshotForClient(clientId, ws, "connect_timeout", null);
+    }, resumeHandshakeTimeoutMs);
+  }
+
+  function sendMessageToClient(clientId, ws, message) {
+    if (!ws || ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    ws.send(message);
+  }
+
+  function getServerResumeState() {
+    if (!getCurrentResumeState) {
+      return { pagesRevision: null, statusRevision: null };
+    }
+    const state = getCurrentResumeState() || {};
+    return {
+      pagesRevision: parseRevision(state.pagesRevision),
+      statusRevision: parseRevision(state.statusRevision),
+    };
+  }
+
+  function formatResumeAck(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.resumeAck,
+      reason: payload.reason || null,
+      sentPages: !!payload.sentPages,
+      sentStatus: !!payload.sentStatus,
+      sentApprovals:
+        Number.isFinite(payload.sentApprovals) && payload.sentApprovals > 0
+          ? Math.floor(payload.sentApprovals)
+          : 0,
+      pagesRevision:
+        payload.pagesRevision === null || payload.pagesRevision === undefined
+          ? null
+          : payload.pagesRevision,
+      statusRevision:
+        payload.statusRevision === null || payload.statusRevision === undefined
+          ? null
+          : payload.statusRevision,
+    });
+  }
+
+  function isSnapshotSynced(sync) {
+    return (
+      !!sync &&
+      sync.pagesSynced &&
+      sync.statusSynced &&
+      sync.approvalsSynced &&
+      sync.debugConfigSynced
+    );
+  }
+
+  function markClientSyncedForType(clientId, messageType) {
+    const sync = syncState.get(clientId);
+    if (!sync) return;
+    if (messageType === "pages" || messageType === APP_PROTOCOL.pages) {
+      sync.pagesSynced = true;
+    }
+    if (messageType === "status" || messageType === APP_PROTOCOL.status) {
+      sync.statusSynced = true;
+    }
+    if (messageType === APP_PROTOCOL.debugConfigSnapshot) {
+      sync.debugConfigSynced = true;
+    }
+    if (isSnapshotSynced(sync) && sync.timer) {
+      clearTimeout(sync.timer);
+      sync.timer = null;
+    }
+  }
+
+  function syncSnapshotForClient(clientId, ws, reason, resumeRequest) {
+    const sync = syncState.get(clientId);
+    if (!sync || isSnapshotSynced(sync)) {
+      const state = getServerResumeState();
+      return {
+        reason,
+        sentPages: false,
+        sentStatus: false,
+        sentApprovals: 0,
+        pagesRevision: state.pagesRevision,
+        statusRevision: state.statusRevision,
+      };
+    }
+
+    if (sync.timer) {
+      clearTimeout(sync.timer);
+      sync.timer = null;
+    }
+
+    const pages = getCurrentPages();
+    const status = getCurrentStatus();
+    const debugConfig = getCurrentDebugConfig ? getCurrentDebugConfig() : null;
+    const state = getServerResumeState();
+    const clientPagesRevision = parseRevision(
+      resumeRequest && resumeRequest.pagesRevision,
+    );
+    const clientStatusRevision = parseRevision(
+      resumeRequest && resumeRequest.statusRevision,
+    );
+    const clientHasPagesState = parseBool(
+      resumeRequest && resumeRequest.hasPagesState,
+    );
+    const clientHasStatusState = parseBool(
+      resumeRequest && resumeRequest.hasStatusState,
+    );
+    const pagesInSync =
+      clientHasPagesState &&
+      state.pagesRevision !== null &&
+      clientPagesRevision !== null &&
+      state.pagesRevision === clientPagesRevision;
+    let sentPages = false;
+    let sentStatus = false;
+    let sentApprovals = 0;
+    let sentDebugConfig = false;
+    if (!sync.pagesSynced) {
+      if (pages === null || pagesInSync) {
+        sync.pagesSynced = true;
+      } else if (ws.readyState === WebSocket.OPEN) {
+        sendMessageToClient(clientId, ws, pages);
+        sentPages = true;
+        sync.pagesSynced = true;
+      }
+    }
+    if (!sync.statusSynced) {
+      // Always replay the current status once per downstream reconnect. The client
+      // uses that fresh status snapshot to clear reconnect UI even when revisions
+      // appear to match after a relay restart.
+      if (status === null) {
+        sync.statusSynced = true;
+      } else if (ws.readyState === WebSocket.OPEN) {
+        sendMessageToClient(clientId, ws, status);
+        sentStatus = true;
+        sync.statusSynced = true;
+      }
+    }
+    if (!sync.approvalsSynced) {
+      if (unresolvedApprovals.size === 0) {
+        sync.approvalsSynced = true;
+      } else {
+        for (const approvalMessage of unresolvedApprovals.values()) {
+          if (ws.readyState !== WebSocket.OPEN) {
+            break;
+          }
+          sendMessageToClient(clientId, ws, approvalMessage);
+          sentApprovals += 1;
+        }
+        sync.approvalsSynced = ws.readyState === WebSocket.OPEN;
+      }
+    }
+    if (!sync.debugConfigSynced) {
+      if (!isAppClient(clientId) || debugConfig === null) {
+        sync.debugConfigSynced = true;
+      } else if (ws.readyState === WebSocket.OPEN) {
+        sendMessageToClient(clientId, ws, debugConfig);
+        sentDebugConfig = true;
+        sync.debugConfigSynced = true;
+      }
+    }
+    if (isSnapshotSynced(sync) && sync.timer) {
+      clearTimeout(sync.timer);
+      sync.timer = null;
+    }
+
+    return {
+      reason,
+      sentPages,
+      sentStatus,
+      sentApprovals,
+      sentDebugConfig,
+      pagesRevision: state.pagesRevision,
+      statusRevision: state.statusRevision,
+    };
+  }
+
+  // When an httpServer is provided, attach to it via noServer mode so HTTP
+  // and WebSocket share a single port.  Otherwise listen on a standalone port
+  // (used when HTTP is disabled and in tests).
+  let wss;
+  if (opts.httpServer) {
+    wss = new WebSocketServer({ noServer: true });
+    opts.httpServer.on("upgrade", (req, socket, head) => {
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      if (url.searchParams.get("token") !== token) {
+        socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+        socket.destroy();
+        return;
+      }
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        wss.emit("connection", ws, req);
+      });
+    });
+  } else {
+    wss = new WebSocketServer({
+      host: opts.host,
+      port: opts.port,
+      verifyClient: ({ req }) => {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        return url.searchParams.get("token") === token;
+      },
+    });
+  }
+
+  wss.on("connection", (ws, req) => {
+    const clientId = `client-${nextClientId++}`;
+    clients.set(clientId, ws);
+    const connectedAtMs = Date.now();
+    const remoteAddress =
+      (req && req.socket && req.socket.remoteAddress) || "unknown";
+    const userAgent =
+      (req && req.headers && req.headers["user-agent"]) || "unknown";
+    const clientMeta = {
+      role: "unknown",
+      firstMessageType: null,
+      textMessageCount: 0,
+      binaryMessageCount: 0,
+      remoteControlCount: 0,
+      connectedEventEmitted: false,
+    };
+    ensureProtocolState(clientId);
+    clientNudgeState.set(clientId, createClientNudgeState());
+    const currentPages = getCurrentPages();
+    const currentStatus = getCurrentStatus();
+    syncState.set(clientId, {
+      pagesSynced: currentPages === null,
+      statusSynced: currentStatus === null,
+      approvalsSynced: unresolvedApprovals.size === 0,
+      debugConfigSynced: !getCurrentDebugConfig,
+      resumeReceived: false,
+      timer: null,
+    });
+    const sync = syncState.get(clientId);
+    if (sync) {
+      sync.timer = setTimeout(() => {
+        sync.timer = null;
+        closeForProtocolViolation(clientId, ws, "protocol_hello_timeout");
+      }, protocolHelloTimeoutMs);
+    }
+    logger.info(
+      `[downstream] ${clientId} connected (${clients.size} total) ip=${remoteAddress} ua=${truncateForLog(String(userAgent), 100)}`,
+    );
+
+    ws.on("error", (err) => {
+      logger.error(`[downstream] ${clientId} error: ${err.message}`);
+    });
+
+    ws.on("message", (data, isBinary) => {
+      // Legacy downstream binary voice transport was removed. Ignore binary frames.
+      if (isBinary) {
+        clientMeta.binaryMessageCount += 1;
+        return;
+      }
+
+      clientMeta.textMessageCount += 1;
+      const raw = data.toString();
+      let parsed = null;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (_) {
+        parsed = null;
+      }
+
+      const protocolHello = parseProtocolHello(parsed);
+
+      if (parsed && typeof parsed.type === "string") {
+        const clientKind = protocolHello
+          ? classifyClientKindFromName(protocolHello.clientName)
+          : "unknown";
+        updateClientRole(clientMeta, parsed.type, clientKind);
+        if (parsed.type === "remote-control") {
+          clientMeta.remoteControlCount += 1;
+        }
+        updateProtocolSessionKey(clientId, parsed.sessionKey);
+      }
+
+      const enrichedPing = parseEnrichedPing(parsed);
+
+      // Intercept application-level ping — respond with pong, skip handler
+      if (enrichedPing) {
+        updateClientNudgeHeartbeat(clientId, enrichedPing);
+        ws.send(JSON.stringify({ type: "pong", ts: parsed.ts }));
+        return;
+      }
+
+      if (protocolHello) {
+        if (!protocolHello.supportedProtocolVersions.includes("v2")) {
+          closeForProtocolViolation(clientId, ws, "protocol_v2_required", {
+            supportedProtocolVersions: protocolHello.supportedProtocolVersions,
+            clientName: protocolHello.clientName,
+            clientVersion: protocolHello.clientVersion,
+            sessionKey: protocolHello.sessionKey,
+          });
+          return;
+        }
+        const protocolClientKind = classifyClientKindFromName(
+          protocolHello.clientName,
+        );
+        if (!externalDebugToolsEnabled && protocolClientKind === "debug") {
+          closeForProtocolViolation(clientId, ws, "external_debug_tools_disabled", {
+            supportedProtocolVersions: protocolHello.supportedProtocolVersions,
+            clientName: protocolHello.clientName,
+            clientVersion: protocolHello.clientVersion,
+            sessionKey: protocolHello.sessionKey,
+          });
+          return;
+        }
+        const state = updateProtocolState(clientId, {
+          selectedVersion: "v2",
+          reason: "negotiated_v2",
+          supportedProtocolVersions: protocolHello.supportedProtocolVersions,
+          clientName: protocolHello.clientName,
+          clientVersion: protocolHello.clientVersion,
+          sessionKey: protocolHello.sessionKey,
+        });
+        logger.info(
+          `[downstream] ${clientId} identified protocol=${state.selectedVersion || "n/a"} client=${describeProtocolClient(state)} kind=${classifyClientKind(state)} session=${state.sessionKey || "n/a"}`,
+        );
+        if (!clientMeta.connectedEventEmitted) {
+          clientMeta.connectedEventEmitted = true;
+          if (onClientConnected) {
+            onClientConnected({
+              clientId,
+              connectedCount: countConnectedAppClients(),
+              connectedAtMs,
+              remoteAddress,
+              userAgent: truncateForLog(String(userAgent), 180),
+              role: clientMeta.role,
+              protocolVersion: state.selectedVersion || null,
+              protocolReason: state.reason || null,
+              clientKind: classifyClientKind(state),
+              clientName: state.clientName || null,
+              clientVersion: state.clientVersion || null,
+              sessionKey: state.sessionKey || null,
+            });
+          }
+        }
+        armResumeHandshakeTimeout(clientId, ws);
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.send(
+            formatProtocolHelloAck({
+              protocolVersion: state.selectedVersion || "v2",
+              supportedProtocolVersions: ["v2"],
+              reason: state.reason,
+            }),
+          );
+        }
+        return;
+      }
+
+      const state = ensureProtocolState(clientId);
+      if (!state.selectedVersion && parsed && typeof parsed.type === "string") {
+        closeForProtocolViolation(clientId, ws, "protocol_hello_required", {
+          clientName: parsed.clientName,
+          clientVersion: parsed.clientVersion,
+          sessionKey: parsed.sessionKey,
+        });
+        return;
+      }
+
+      if (
+        state.selectedVersion === "v2" &&
+        parsed &&
+        REMOVED_V1_APP_TYPES.has(parsed.type)
+      ) {
+        return;
+      }
+
+      if (parsed && parsed.type === APP_PROTOCOL.resume) {
+        const sync = syncState.get(clientId);
+        if (sync) sync.resumeReceived = true;
+        const ack = syncSnapshotForClient(clientId, ws, "resume", parsed);
+        if (ws.readyState === WebSocket.OPEN) {
+          sendMessageToClient(clientId, ws, formatResumeAck(ack));
+        }
+        return;
+      }
+
+      const visibilityControl = parseVisibilityControl(parsed);
+      const drainCompleteControl = parseDrainCompleteControl(parsed);
+      const transportControl = visibilityControl || drainCompleteControl;
+      if (transportControl) {
+        const protocol = protocolState.get(clientId);
+        if (transportControl.type === "visibility") {
+          updateClientVisibilityState(clientId, transportControl.state);
+        } else {
+          setClientInteractionStage(clientId, "idle", {
+            reason: "drain_complete",
+            deactivateImmediately: true,
+          });
+        }
+        const meta = {
+          clientId,
+          controlType: transportControl.type,
+          state: transportControl.type === "visibility" ? transportControl.state : null,
+          connectedCount: countConnectedAppClients(),
+          role: clientMeta.role,
+          clientKind: classifyClientKind(protocol),
+          clientName: protocol && protocol.clientName ? protocol.clientName : null,
+          clientVersion: protocol && protocol.clientVersion ? protocol.clientVersion : null,
+          protocolVersion:
+            protocol && protocol.selectedVersion ? protocol.selectedVersion : null,
+          sessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
+        };
+        if (transportControl.type === "visibility") {
+          logger.info(
+            `[downstream] ${clientId} transport visibility state=${transportControl.state} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
+          );
+        } else {
+          logger.info(
+            `[downstream] ${clientId} transport control=${transportControl.type} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"}`,
+          );
+        }
+        if (onTransportControl) {
+          onTransportControl(meta);
+        }
+        return;
+      }
+
+      const result = handler.handleMessage(clientId, raw);
+      processResult(clientId, result);
+    });
+
+    ws.on("close", (code, reasonBuffer) => {
+      const sync = syncState.get(clientId);
+      if (sync && sync.timer) {
+        clearTimeout(sync.timer);
+      }
+      const protocol = protocolState.get(clientId);
+      syncState.delete(clientId);
+      protocolState.delete(clientId);
+      clearClientNudgeTimers(clientId);
+      clientNudgeState.delete(clientId);
+      handler.removeClient(clientId);
+      clients.delete(clientId);
+      const lifetimeMs = Date.now() - connectedAtMs;
+      const reason =
+        reasonBuffer && reasonBuffer.length > 0
+          ? truncateForLog(reasonBuffer.toString("utf8").replace(/\s+/g, " "), 120)
+          : "";
+      logger.info(
+        `[downstream] ${clientId} disconnected (${clients.size} total) code=${code} reason="${reason}" lifetimeMs=${lifetimeMs} role=${clientMeta.role} client=${describeProtocolClient(protocol)} kind=${classifyClientKind(protocol)} protocol=${protocol && protocol.selectedVersion ? protocol.selectedVersion : "n/a"} session=${protocol && protocol.sessionKey ? protocol.sessionKey : "n/a"} firstType=${clientMeta.firstMessageType || "n/a"} textMsgs=${clientMeta.textMessageCount} binMsgs=${clientMeta.binaryMessageCount} remoteCtrlMsgs=${clientMeta.remoteControlCount}`,
+      );
+      if (onClientDisconnected && clientMeta.connectedEventEmitted) {
+        onClientDisconnected({
+          clientId,
+          connectedCount: countConnectedAppClients(),
+          connectedAtMs,
+          lifetimeMs,
+          closeCode: code,
+          closeReason: reason,
+          role: clientMeta.role,
+          protocolVersion:
+            protocol && protocol.selectedVersion ? protocol.selectedVersion : null,
+          protocolReason: protocol && protocol.reason ? protocol.reason : null,
+          clientKind: classifyClientKind(protocol),
+          clientName: protocol && protocol.clientName ? protocol.clientName : null,
+          clientVersion:
+            protocol && protocol.clientVersion ? protocol.clientVersion : null,
+          sessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
+          firstMessageType: clientMeta.firstMessageType || null,
+          textMessageCount: clientMeta.textMessageCount,
+          binaryMessageCount: clientMeta.binaryMessageCount,
+          remoteControlCount: clientMeta.remoteControlCount,
+        });
+      }
+    });
+  });
+
+  /**
+   * Process the result from handler.handleMessage.
+   *
+   * Handles both synchronous values and promises. Dispatches unicast
+   * or broadcast actions as appropriate.
+   *
+   * @param {string} senderId - Client ID that sent the original message
+   * @param {object|null|Promise} result - Handler return value
+   */
+  function processResult(senderId, result) {
+    if (result === null || result === undefined) {
+      return;
+    }
+
+    if (typeof result.then === "function") {
+      result.then(
+        (resolved) => processResult(senderId, resolved),
+        (err) => {
+          logger.error(
+            `[downstream] Error processing message from ${senderId}:`,
+            err,
+          );
+        },
+      );
+      return;
+    }
+
+    if (result.unicast) {
+      const ws = clients.get(senderId);
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        sendMessageToClient(senderId, ws, result.unicast);
+      }
+    }
+
+    if (result.broadcast) {
+      if (Array.isArray(result.broadcast)) {
+        for (const msg of result.broadcast) broadcast(msg);
+      } else {
+        broadcast(result.broadcast);
+      }
+    }
+
+    if (result.broadcastApp) {
+      if (Array.isArray(result.broadcastApp)) {
+        for (const msg of result.broadcastApp) broadcastApp(msg);
+      } else {
+        broadcastApp(result.broadcastApp);
+      }
+    }
+  }
+
+  /**
+   * Send a message to all connected clients.
+   *
+   * @param {string} message - JSON string to send
+   */
+  function broadcast(message) {
+    let messageType = null;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(message);
+      if (parsed && typeof parsed.type === "string") {
+        messageType = parsed.type;
+      }
+    } catch (_) {
+      messageType = null;
+    }
+
+    if (
+      (messageType === "approval" || messageType === APP_PROTOCOL.approvalRequest) &&
+      parsed &&
+      typeof parsed.id === "string"
+    ) {
+      const approvalId = parsed.id.trim();
+      if (approvalId) {
+        unresolvedApprovals.set(approvalId, message);
+      }
+    } else if (
+      (messageType === "approvalResolved" ||
+        messageType === APP_PROTOCOL.approvalResolved) &&
+      parsed &&
+      typeof parsed.id === "string"
+    ) {
+      const approvalId = parsed.id.trim();
+      if (approvalId) {
+        unresolvedApprovals.delete(approvalId);
+      }
+    }
+
+    const relayStreamingActivityAtMs = isStreamingBroadcastType(messageType)
+      ? Date.now()
+      : null;
+    for (const [clientId, ws] of clients) {
+      if (ws.readyState === WebSocket.OPEN) {
+        sendMessageToClient(clientId, ws, message);
+        if (relayStreamingActivityAtMs !== null) {
+          ensureClientNudgeState(clientId).lastRelayStreamingActivityAtMs =
+            relayStreamingActivityAtMs;
+        }
+        if (
+          messageType === "pages" ||
+          messageType === "status" ||
+          messageType === APP_PROTOCOL.pages ||
+          messageType === APP_PROTOCOL.status
+        ) {
+          markClientSyncedForType(clientId, messageType);
+        }
+      }
+    }
+    applyBroadcastInteractionStage(messageType, parsed, relayStreamingActivityAtMs);
+  }
+
+  /**
+   * Send a message to all connected app/WebUI clients.
+   *
+   * @param {string} message - JSON string to send
+   */
+  function broadcastApp(message) {
+    let messageType = null;
+    try {
+      const parsed = JSON.parse(message);
+      if (parsed && typeof parsed.type === "string") {
+        messageType = parsed.type;
+      }
+    } catch (_) {
+      messageType = null;
+    }
+
+    for (const [clientId, ws] of clients) {
+      if (!isAppClient(clientId)) {
+        continue;
+      }
+      if (ws.readyState !== WebSocket.OPEN) {
+        continue;
+      }
+      sendMessageToClient(clientId, ws, message);
+      if (
+        messageType === "pages" ||
+        messageType === "status" ||
+        messageType === APP_PROTOCOL.pages ||
+        messageType === APP_PROTOCOL.status ||
+        messageType === APP_PROTOCOL.debugConfigSnapshot
+      ) {
+        markClientSyncedForType(clientId, messageType);
+      }
+    }
+  }
+
+  /**
+   * Send a message to a specific client.
+   *
+   * @param {string} clientId - Target client ID
+   * @param {string} message - JSON string to send
+   */
+  function unicast(clientId, message) {
+    const ws = clients.get(clientId);
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      sendMessageToClient(clientId, ws, message);
+    }
+  }
+
+  /**
+   * Get all connected client IDs.
+   *
+   * @returns {string[]}
+   */
+  function getClientIds() {
+    return Array.from(clients.keys());
+  }
+
+  function getConnectedAppCount(excludeClientId = null) {
+    return countConnectedAppClients(excludeClientId);
+  }
+
+  /**
+   * Shut down the WebSocket server and disconnect all clients.
+   *
+   * @returns {Promise<void>}
+   */
+  function close() {
+    return new Promise((resolve) => {
+      for (const [, sync] of syncState) {
+        if (sync.timer) clearTimeout(sync.timer);
+      }
+      syncState.clear();
+      for (const [clientId] of clientNudgeState) {
+        clearClientNudgeTimers(clientId);
+      }
+      clientNudgeState.clear();
+      for (const [, ws] of clients) {
+        ws.close();
+      }
+      clients.clear();
+      wss.close(() => resolve());
+    });
+  }
+
+  return {
+    broadcast,
+    unicast,
+    getClientIds,
+    getConnectedAppCount,
+    closeConnectedAppClients,
+    getClientNudgeState(clientId) {
+      return cloneClientNudgeState(clientNudgeState.get(clientId) || null);
+    },
+    close,
+    get httpServer() {
+      return opts.httpServer || null;
+    },
+    /** Underlying WebSocket.Server (for reading address, etc.) */
+    get wss() {
+      return wss;
+    },
+  };
+}
+
+export { createDownstreamServer };