ocuclaw 1.3.0 → 1.3.2

package/dist/runtime/downstream-server.js

@@ -1,2057 +0,0 @@
-import * as WebSocketModule from "ws";
-import { createRelayClientNudgeController } from "./relay-client-nudge-controller.js";
-import * as RelayWorkerProtocol from "./relay-worker-protocol.js";
-
-// `ws` exposes different server entrypoints across ESM/CJS consumers.
-const WebSocket =
-  WebSocketModule.default || WebSocketModule.WebSocket || WebSocketModule;
-const WebSocketServer =
-  WebSocketModule.WebSocketServer || WebSocketModule.Server || WebSocket.Server;
-
-// Bounded wait for the single app client to answer a forwarded automation
-// state request. Pending entries are otherwise cleared only by a matching
-// reply or a disconnect, so a connected-but-silent app would leave the
-// requester waiting forever.
-const AUTOMATION_STATE_REPLY_TIMEOUT_MS = 1500;
-
-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 getAgentAvatarDataUriByHash =
-    typeof opts.getAgentAvatarDataUriByHash === "function"
-      ? opts.getAgentAvatarDataUriByHash
-      : () => null;
-  const token = opts.token;
-  const onClientConnected = opts.onClientConnected || null;
-  const onClientDisconnected = opts.onClientDisconnected || null;
-  const onTransportControl = opts.onTransportControl || null;
-  const relayHealth = opts.relayHealth || null;
-  const sendBufferSnapshotForTest =
-    typeof opts.sendBufferSnapshotForTest === "function"
-      ? opts.sendBufferSnapshotForTest
-      : null;
-  const getPluginVersion =
-    typeof opts.getPluginVersion === "function" ? opts.getPluginVersion : null;
-  const getRequiresClientVersion =
-    typeof opts.getRequiresClientVersion === "function" ? opts.getRequiresClientVersion : null;
-  const pluginId =
-    typeof opts.pluginId === "string" && opts.pluginId.trim().length > 0
-      ? opts.pluginId.trim()
-      : null;
-  const runPluginUpdate =
-    typeof opts.runPluginUpdate === "function" ? opts.runPluginUpdate : null;
-  const runGatewayRestart =
-    typeof opts.runGatewayRestart === "function" ? opts.runGatewayRestart : null;
-  const sessionService =
-    opts.sessionService && typeof opts.sessionService === "object"
-      ? opts.sessionService
-      : null;
-  const protocolHelloTimeoutMs = Number.isFinite(opts.protocolHelloTimeoutMs)
-    ? Math.max(0, Math.floor(opts.protocolHelloTimeoutMs))
-    : 10000;
-  const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
-  const resumeHandshakeTimeoutMs = Number.isFinite(opts.resumeHandshakeTimeoutMs)
-    ? Math.max(0, Math.floor(opts.resumeHandshakeTimeoutMs))
-    : 1500;
-  /** @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, {clientDebugEnabled: boolean|null, runtimeDiagnosticsVisible: boolean|null, perfNoisyDebugMuted: boolean|null, perfPayloadLiteMode: boolean|null, activeSessionKey: string|null, bundleIdentity: {kind: string|null, mode: string|null, host: string|null, port: number|null, servedDistPath: string|null}|null, runtimeContext: string|null, glasses: {connected: boolean, batteryPercent: number|null, statusAgeMs: number|null}|null, emittedAtMs: number|null, updatedAtMs: number}>} */
-  const clientReadinessSnapshotState = new Map();
-  /** @type {Map<string, {requesterClientId: string, targetClientId: string, createdAtMs: number}>} */
-  const pendingReadinessProbeRequests = new Map();
-  /** @type {Map<string, {requesterClientId: string, targetClientId: string, createdAtMs: number, expiryTimer: any}>} */
-  const pendingAutomationStateRequests = new Map();
-  /** @type {Map<string, string>} */
-  const unresolvedApprovals = new Map();
-  const nudgeController = createRelayClientNudgeController({
-    thresholds: {
-      nudgeActiveIntervalMs: opts.nudgeActiveIntervalMs,
-      nudgeSlowIntervalMs: opts.nudgeSlowIntervalMs,
-      nudgeIdleDeactivateMs: opts.nudgeIdleDeactivateMs,
-      nudgeHeartbeatIntervalMs: opts.nudgeHeartbeatIntervalMs,
-      nudgeHardTimeoutMs: opts.nudgeHardTimeoutMs,
-    },
-    isAppClient,
-    sendFrame(clientId, frame) {
-      const ws = clients.get(clientId);
-      if (!ws || ws.readyState !== WebSocket.OPEN) return false;
-      sendMessageToClient(clientId, ws, frame);
-      return true;
-    },
-  });
-  let nextClientId = 1;
-  let pendingHandlerPromiseCount = 0;
-  const APP_PROTOCOL = {
-    approvalRequest: "ocuclaw.approval.request",
-    approvalResolved: "ocuclaw.approval.resolved",
-    automationStateGet: "ocuclaw.automation.state.get",
-    automationStateSnapshot: "ocuclaw.automation.state.snapshot",
-    avatarBlob: "ocuclaw.avatar.blob",
-    avatarFetch: "ocuclaw.avatar.fetch",
-    debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
-    pages: "ocuclaw.view.pages.snapshot",
-    readinessProbeAck: "ocuclaw.readiness.probe.ack",
-    readinessProbeRequest: "ocuclaw.readiness.probe.request",
-    readinessSnapshot: "ocuclaw.readiness.snapshot",
-    resume: "ocuclaw.sync.resume",
-    resumeAck: "ocuclaw.sync.resume.ack",
-    restartGateway: "ocuclaw.restartGateway",
-    restartGatewayAck: "ocuclaw.restartGatewayAck",
-    status: "ocuclaw.runtime.status",
-    updatePlugin: "ocuclaw.updatePlugin",
-    updatePluginResult: "ocuclaw.updatePluginResult",
-  };
-  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" ||
-      messageType === APP_PROTOCOL.automationStateGet
-        ? "control"
-        : "app";
-    if (meta.role === "unknown") {
-      meta.role = nextRole;
-      return;
-    }
-    if (meta.role !== nextRole) {
-      meta.role = "mixed";
-    }
-  }
-
-  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 parseOptionalBoolean(value) {
-    if (value === true || value === false) return value;
-    if (typeof value === "number") return value !== 0;
-    if (typeof value !== "string") return null;
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "true" || normalized === "1" || normalized === "yes") {
-      return true;
-    }
-    if (normalized === "false" || normalized === "0" || normalized === "no") {
-      return false;
-    }
-    return null;
-  }
-
-  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),
-      readinessSnapshot: parseReadinessSnapshot(value.readinessSnapshot),
-    };
-  }
-
-  function parseReadinessBundleIdentity(value) {
-    if (!value || typeof value !== "object") {
-      return null;
-    }
-    const kind = parseOptionalTrimmedString(value.kind || value.lane);
-    const mode = parseOptionalTrimmedString(value.mode);
-    const host = parseOptionalTrimmedString(value.host);
-    const port = parseOptionalNonNegativeInt(value.port);
-    const servedDistPath =
-      parseOptionalTrimmedString(value.servedDistPath) ||
-      parseOptionalTrimmedString(value.staticDir);
-    if (!kind && !mode && !host && port === null && !servedDistPath) {
-      return null;
-    }
-    return {
-      kind: kind || null,
-      mode: mode || null,
-      host: host || null,
-      port,
-      servedDistPath: servedDistPath || null,
-    };
-  }
-
-  function parseReadinessRuntimeContext(value) {
-    const s = parseOptionalTrimmedString(value);
-    return s === "native_app" || s === "simulator" || s === "browser" ? s : null;
-  }
-
-  function parseReadinessGlasses(value) {
-    if (!value || typeof value !== "object") {
-      return null;
-    }
-    const connected = parseOptionalBoolean(value.connected);
-    if (connected === null) {
-      return null;
-    }
-    let batteryPercent = parseOptionalNonNegativeInt(value.batteryPercent);
-    if (batteryPercent !== null) {
-      batteryPercent = Math.min(100, batteryPercent);
-    }
-    const statusAgeMs = parseOptionalNonNegativeInt(value.statusAgeMs);
-    return { connected, batteryPercent, statusAgeMs };
-  }
-
-  function parseReadinessSnapshot(value) {
-    if (!value || typeof value !== "object") {
-      return null;
-    }
-    const clientDebugEnabled = parseOptionalBoolean(value.clientDebugEnabled);
-    const runtimeDiagnosticsVisible = parseOptionalBoolean(
-      value.runtimeDiagnosticsVisible,
-    );
-    const perfNoisyDebugMuted = parseOptionalBoolean(value.perfNoisyDebugMuted);
-    const perfPayloadLiteMode = parseOptionalBoolean(value.perfPayloadLiteMode);
-    const activeSessionKey =
-      parseOptionalTrimmedString(value.activeSessionKey) ||
-      parseOptionalTrimmedString(value.sessionKey);
-    const bundleIdentity = parseReadinessBundleIdentity(
-      value.bundleIdentity || value.bundle,
-    );
-    const runtimeContext = parseReadinessRuntimeContext(value.runtimeContext);
-    const glasses = parseReadinessGlasses(value.glasses);
-    const emittedAtMs = parseOptionalNonNegativeInt(value.emittedAtMs);
-    if (
-      clientDebugEnabled === null &&
-      runtimeDiagnosticsVisible === null &&
-      perfNoisyDebugMuted === null &&
-      perfPayloadLiteMode === null &&
-      !activeSessionKey &&
-      !bundleIdentity &&
-      !runtimeContext &&
-      !glasses &&
-      emittedAtMs === null
-    ) {
-      return null;
-    }
-    return {
-      clientDebugEnabled,
-      runtimeDiagnosticsVisible,
-      perfNoisyDebugMuted,
-      perfPayloadLiteMode,
-      activeSessionKey: activeSessionKey || null,
-      bundleIdentity,
-      runtimeContext,
-      glasses,
-      emittedAtMs,
-      updatedAtMs: Date.now(),
-    };
-  }
-
-  function parseReadinessProbeAck(value) {
-    if (!value || value.type !== APP_PROTOCOL.readinessProbeAck) {
-      return null;
-    }
-    const requestId = parseOptionalTrimmedString(value.requestId);
-    if (!requestId) {
-      return null;
-    }
-    return {
-      requestId,
-      ok: value.ok !== false,
-      reasonCode: parseOptionalTrimmedString(value.reasonCode),
-      message: parseOptionalTrimmedString(value.message),
-      activeSessionKey:
-        parseOptionalTrimmedString(value.activeSessionKey) ||
-        parseOptionalTrimmedString(value.sessionKey),
-      emittedAtMs: parseOptionalNonNegativeInt(value.emittedAtMs),
-    };
-  }
-
-  function parseAutomationStateSnapshot(value) {
-    if (!value || value.type !== APP_PROTOCOL.automationStateSnapshot) {
-      return null;
-    }
-    const requestId = parseOptionalTrimmedString(value.requestId);
-    if (!requestId) {
-      return null;
-    }
-    return {
-      requestId,
-      ok: value.ok !== false,
-      state: value.state && typeof value.state === "object" ? value.state : null,
-      reasonCode: parseOptionalTrimmedString(value.reasonCode),
-      message: parseOptionalTrimmedString(value.message),
-    };
-  }
-
-  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, sessionKey = null) {
-    let count = 0;
-    for (const [clientId, ws] of clients) {
-      if (excludeClientId && clientId === excludeClientId) {
-        continue;
-      }
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        continue;
-      }
-      const protocol = protocolState.get(clientId);
-      if (classifyClientKind(protocol) !== "app") {
-        continue;
-      }
-      // When sessionKey is provided, only count app clients bound to that
-      // session — lets callers ask "is this session's last app gone?"
-      // without being masked by apps in other sessions.
-      if (sessionKey != null && (!protocol || protocol.sessionKey !== sessionKey)) {
-        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 formatProtocolHelloAck(payload) {
-    const pluginVersion = getPluginVersion ? getPluginVersion() : null;
-    const requiresClientVersion = getRequiresClientVersion ? getRequiresClientVersion() : null;
-    return RelayWorkerProtocol.formatProtocolHelloAck({
-      protocolVersion: payload.protocolVersion,
-      supportedProtocolVersions: payload.supportedProtocolVersions || ["v2"],
-      reason: payload.reason,
-      pluginVersion,
-      requiresClientVersion,
-      pluginId,
-    });
-  }
-
-  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 cloneReadinessBundleIdentity(value) {
-    if (!value) return null;
-    return {
-      kind: value.kind || null,
-      mode: value.mode || null,
-      host: value.host || null,
-      port: Number.isFinite(value.port) ? value.port : null,
-      servedDistPath: value.servedDistPath || null,
-    };
-  }
-
-  function cloneReadinessGlasses(value) {
-    if (!value) return null;
-    // The dedicated ocuclaw.readiness.snapshot frame is stored raw via clone
-    // (no parseReadinessGlasses pass), so clamp/validate defensively here too.
-    const batteryPercent = Number.isFinite(value.batteryPercent)
-      ? Math.min(100, Math.max(0, value.batteryPercent))
-      : null;
-    const statusAgeMs =
-      Number.isFinite(value.statusAgeMs) && value.statusAgeMs >= 0
-        ? value.statusAgeMs
-        : null;
-    return {
-      connected: value.connected === true,
-      batteryPercent,
-      statusAgeMs,
-    };
-  }
-
-  function cloneReadinessSnapshot(value) {
-    if (!value) return null;
-    return {
-      clientDebugEnabled:
-        value.clientDebugEnabled === true || value.clientDebugEnabled === false
-          ? value.clientDebugEnabled
-          : null,
-      runtimeDiagnosticsVisible:
-        value.runtimeDiagnosticsVisible === true ||
-        value.runtimeDiagnosticsVisible === false
-          ? value.runtimeDiagnosticsVisible
-          : null,
-      perfNoisyDebugMuted:
-        value.perfNoisyDebugMuted === true || value.perfNoisyDebugMuted === false
-          ? value.perfNoisyDebugMuted
-          : null,
-      perfPayloadLiteMode:
-        value.perfPayloadLiteMode === true || value.perfPayloadLiteMode === false
-          ? value.perfPayloadLiteMode
-          : null,
-      activeSessionKey: value.activeSessionKey || null,
-      bundleIdentity: cloneReadinessBundleIdentity(value.bundleIdentity),
-      runtimeContext:
-        value.runtimeContext === "native_app" ||
-        value.runtimeContext === "simulator" ||
-        value.runtimeContext === "browser"
-          ? value.runtimeContext
-          : null,
-      glasses: cloneReadinessGlasses(value.glasses),
-      emittedAtMs: Number.isFinite(value.emittedAtMs) ? value.emittedAtMs : null,
-      updatedAtMs: Number.isFinite(value.updatedAtMs) ? value.updatedAtMs : null,
-    };
-  }
-
-  function updateClientReadinessSnapshot(clientId, snapshot) {
-    if (!clientId || !snapshot) return null;
-    const next = cloneReadinessSnapshot({
-      ...snapshot,
-      updatedAtMs: Date.now(),
-    });
-    clientReadinessSnapshotState.set(clientId, next);
-    return next;
-  }
-
-  function clearPendingReadinessProbesForClient(clientId) {
-    if (!clientId) return;
-    for (const [requestId, pending] of pendingReadinessProbeRequests) {
-      if (!pending) continue;
-      if (
-        pending.requesterClientId === clientId ||
-        pending.targetClientId === clientId
-      ) {
-        pendingReadinessProbeRequests.delete(requestId);
-      }
-    }
-  }
-
-  function clearPendingAutomationStateRequestsForClient(clientId) {
-    if (!clientId) return;
-    for (const [requestId, pending] of pendingAutomationStateRequests) {
-      if (!pending) continue;
-      if (
-        pending.requesterClientId === clientId ||
-        pending.targetClientId === clientId
-      ) {
-        if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
-        pendingAutomationStateRequests.delete(requestId);
-      }
-    }
-  }
-
-  function buildReadinessClientEntry(clientId) {
-    const protocol = protocolState.get(clientId);
-    return {
-      clientId,
-      clientKind: classifyClientKind(protocol),
-      clientName: protocol && protocol.clientName ? protocol.clientName : null,
-      clientVersion: protocol && protocol.clientVersion ? protocol.clientVersion : null,
-      protocolSessionKey: protocol && protocol.sessionKey ? protocol.sessionKey : null,
-      readinessSnapshot: cloneReadinessSnapshot(
-        clientReadinessSnapshotState.get(clientId) || null,
-      ),
-    };
-  }
-
-  function isStreamingBroadcastType(messageType) {
-    return (
-      messageType === "streaming" ||
-      messageType === "ocuclaw.message.stream.delta"
-    );
-  }
-
-  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 parseMessageTypeForHealth(message) {
-    try {
-      const parsed = JSON.parse(message);
-      return parsed && typeof parsed.type === "string" ? parsed.type : null;
-    } catch (_) {
-      return null;
-    }
-  }
-
-  function sendMessageToClient(clientId, ws, message, knownMessageType) {
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    ws.send(message);
-    if (relayHealth && typeof relayHealth.observeSendBuffer === "function") {
-      const bufferedAmountBytes = sendBufferSnapshotForTest
-        ? sendBufferSnapshotForTest(ws)
-        : Number.isFinite(ws.bufferedAmount)
-          ? ws.bufferedAmount
-          : null;
-      relayHealth.observeSendBuffer({
-        clientId,
-        messageType:
-          knownMessageType !== undefined
-            ? knownMessageType
-            : parseMessageTypeForHealth(message),
-        bufferedAmountBytes,
-      });
-    }
-  }
-
-  function forwardReadinessProbeAck(clientId, ack) {
-    if (!ack || !ack.requestId) {
-      return;
-    }
-    const pending = pendingReadinessProbeRequests.get(ack.requestId);
-    if (!pending || pending.targetClientId !== clientId) {
-      return;
-    }
-    pendingReadinessProbeRequests.delete(ack.requestId);
-    const requesterWs = clients.get(pending.requesterClientId);
-    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    const protocol = protocolState.get(clientId);
-    const message =
-      handler && typeof handler.formatReadinessProbeAck === "function"
-        ? handler.formatReadinessProbeAck({
-            ok: ack.ok !== false,
-            requestId: ack.requestId,
-            reasonCode: ack.reasonCode || null,
-            message: ack.message || null,
-            activeSessionKey: ack.activeSessionKey || null,
-            emittedAtMs: ack.emittedAtMs,
-            clientId,
-            clientName: protocol && protocol.clientName ? protocol.clientName : null,
-            clientVersion:
-              protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          })
-        : JSON.stringify({
-            type: APP_PROTOCOL.readinessProbeAck,
-            ok: ack.ok !== false,
-            requestId: ack.requestId,
-            reasonCode: ack.reasonCode || null,
-            message: ack.message || null,
-            activeSessionKey: ack.activeSessionKey || null,
-            emittedAtMs: ack.emittedAtMs,
-            clientId,
-            clientName: protocol && protocol.clientName ? protocol.clientName : null,
-            clientVersion:
-              protocol && protocol.clientVersion ? protocol.clientVersion : null,
-          });
-    sendMessageToClient(pending.requesterClientId, requesterWs, message);
-  }
-
-  function forwardAutomationStateSnapshot(clientId, snapshot) {
-    if (!snapshot || !snapshot.requestId) {
-      return;
-    }
-    const pending = pendingAutomationStateRequests.get(snapshot.requestId);
-    if (!pending || pending.targetClientId !== clientId) {
-      return;
-    }
-    if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
-    pendingAutomationStateRequests.delete(snapshot.requestId);
-    const requesterWs = clients.get(pending.requesterClientId);
-    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    const message =
-      handler && typeof handler.formatAutomationStateSnapshot === "function"
-        ? handler.formatAutomationStateSnapshot({
-            ok: snapshot.ok !== false,
-            requestId: snapshot.requestId,
-            state: snapshot.state || null,
-            reasonCode: snapshot.reasonCode || null,
-            message: snapshot.message || null,
-          })
-        : JSON.stringify({
-            type: APP_PROTOCOL.automationStateSnapshot,
-            ok: snapshot.ok !== false,
-            requestId: snapshot.requestId,
-            state: snapshot.state || null,
-            reasonCode: snapshot.reasonCode || null,
-            message: snapshot.message || null,
-          });
-    sendMessageToClient(pending.requesterClientId, requesterWs, message);
-  }
-
-  function expirePendingAutomationStateRequest(requestId) {
-    const pending = pendingAutomationStateRequests.get(requestId);
-    if (!pending) {
-      return;
-    }
-    if (pending.expiryTimer) clearTimeout(pending.expiryTimer);
-    pendingAutomationStateRequests.delete(requestId);
-    const requesterWs = clients.get(pending.requesterClientId);
-    if (!requesterWs || requesterWs.readyState !== WebSocket.OPEN) {
-      return;
-    }
-    const message =
-      handler && typeof handler.formatAutomationStateSnapshot === "function"
-        ? handler.formatAutomationStateSnapshot({
-            ok: false,
-            requestId,
-            state: null,
-            reasonCode: "snapshot_unavailable",
-            message: "Automation state snapshot is unavailable",
-          })
-        : JSON.stringify({
-            type: APP_PROTOCOL.automationStateSnapshot,
-            ok: false,
-            requestId,
-            state: null,
-            reasonCode: "snapshot_unavailable",
-            message: "Automation state snapshot is unavailable",
-          });
-    sendMessageToClient(pending.requesterClientId, requesterWs, message);
-  }
-
-  function buildAutomationStateDispatchResult(senderId, parsed) {
-    const requestId = parseOptionalTrimmedString(parsed && parsed.requestId);
-    const sessionKey = parseOptionalTrimmedString(parsed && parsed.sessionKey);
-    const snapshot = getReadinessSnapshot();
-    const targetEntry =
-      snapshot &&
-      snapshot.connectedClientCount === 1 &&
-      snapshot.fanoutRecipientCount === 1 &&
-      Array.isArray(snapshot.clients) &&
-      snapshot.clients.length === 1
-        ? snapshot.clients[0]
-        : null;
-    const targetClientId =
-      targetEntry && typeof targetEntry.clientId === "string"
-        ? targetEntry.clientId
-        : null;
-    const readinessPublished =
-      !!(
-        targetEntry &&
-        targetEntry.readinessSnapshot &&
-        Number.isFinite(targetEntry.readinessSnapshot.emittedAtMs)
-      );
-
-    const formatFailure = (reasonCode, message) => ({
-      unicast:
-        handler && typeof handler.formatAutomationStateSnapshot === "function"
-          ? handler.formatAutomationStateSnapshot({
-              ok: false,
-              requestId,
-              reasonCode,
-              message,
-            })
-          : JSON.stringify({
-              type: APP_PROTOCOL.automationStateSnapshot,
-              ok: false,
-              requestId,
-              reasonCode,
-              message,
-            }),
-    });
-
-    if (!requestId) {
-      return formatFailure(
-        "snapshot_unavailable",
-        "automation state request requires requestId",
-      );
-    }
-    if (
-      !snapshot ||
-      snapshot.connectedClientCount <= 0 ||
-      snapshot.fanoutRecipientCount <= 0
-    ) {
-      return formatFailure("no_downstream_client", "No downstream app client connected");
-    }
-    if (
-      snapshot.connectedClientCount > 1 ||
-      snapshot.fanoutRecipientCount > 1 ||
-      !targetClientId
-    ) {
-      return formatFailure(
-        "multi_recipient_fanout",
-        "Multiple downstream app clients connected",
-      );
-    }
-    if (!readinessPublished) {
-      return formatFailure(
-        "snapshot_unavailable",
-        "Automation state snapshot is unavailable",
-      );
-    }
-    return {
-      automationStateRequest: {
-        requestId,
-        targetClientId,
-        message:
-          handler && typeof handler.formatAutomationStateRequest === "function"
-            ? handler.formatAutomationStateRequest({
-                requestId,
-                sessionKey: sessionKey || null,
-              })
-            : JSON.stringify({
-                type: APP_PROTOCOL.automationStateGet,
-                requestId,
-                sessionKey: sessionKey || null,
-              }),
-      },
-    };
-  }
-
-  function getServerResumeState() {
-    if (!getCurrentResumeState) {
-      return { pagesRevision: null, statusRevision: null };
-    }
-    const state = getCurrentResumeState() || {};
-    return {
-      pagesRevision: RelayWorkerProtocol.parseNonNegativeRevision(
-        state.pagesRevision,
-      ),
-      statusRevision: RelayWorkerProtocol.parseNonNegativeRevision(
-        state.statusRevision,
-      ),
-    };
-  }
-
-  function formatResumeAck(payload) {
-    return RelayWorkerProtocol.formatResumeAck(payload);
-  }
-
-  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 = RelayWorkerProtocol.parseNonNegativeRevision(
-      resumeRequest && resumeRequest.pagesRevision,
-    );
-    const clientStatusRevision = RelayWorkerProtocol.parseNonNegativeRevision(
-      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) => {
-      wss.handleUpgrade(req, socket, head, (ws) => {
-        wss.emit("connection", ws, req);
-      });
-    });
-  } else {
-    wss = new WebSocketServer({
-      host: opts.host,
-      port: opts.port,
-    });
-  }
-
-  wss.on("connection", (ws, req) => {
-    const requestUrl = new URL(req.url, `http://${req.headers.host}`);
-    if (requestUrl.searchParams.get("token") !== token) {
-      ws.close(4001, "invalid_token");
-      return;
-    }
-    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);
-    nudgeController.addClient(clientId);
-    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) {
-        nudgeController.updateHeartbeat(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,
-        });
-        if (protocolHello.readinessSnapshot) {
-          updateClientReadinessSnapshot(clientId, protocolHello.readinessSnapshot);
-        }
-        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.readinessSnapshot) {
-        if (classifyClientKind(state) === "app") {
-          updateClientReadinessSnapshot(clientId, parsed);
-        }
-        return;
-      }
-
-      const readinessProbeAck = parseReadinessProbeAck(parsed);
-      if (readinessProbeAck) {
-        if (classifyClientKind(state) === "app") {
-          forwardReadinessProbeAck(clientId, readinessProbeAck);
-        }
-        return;
-      }
-
-      const automationStateSnapshot = parseAutomationStateSnapshot(parsed);
-      if (automationStateSnapshot) {
-        if (classifyClientKind(state) === "app") {
-          forwardAutomationStateSnapshot(clientId, automationStateSnapshot);
-        }
-        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;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.automationStateGet) {
-        const result = handler.handleMessage(clientId, raw);
-        if (result !== null && result !== undefined) {
-          processResult(clientId, result);
-        } else {
-          processResult(clientId, buildAutomationStateDispatchResult(clientId, parsed));
-        }
-        return;
-      }
-
-      const visibilityControl = parseVisibilityControl(parsed);
-      const drainCompleteControl = parseDrainCompleteControl(parsed);
-      const transportControl = visibilityControl || drainCompleteControl;
-      if (transportControl) {
-        const protocol = protocolState.get(clientId);
-        if (transportControl.type === "visibility") {
-          nudgeController.updateVisibilityState(clientId, transportControl.state);
-        } else {
-          nudgeController.setInteractionStage(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;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.updatePlugin) {
-        if (!runPluginUpdate) {
-          logger.warn(
-            `[downstream] ${clientId} updatePlugin requested but no runPluginUpdate is configured`,
-          );
-          return;
-        }
-        const requestId =
-          parseOptionalTrimmedString(parsed.requestId) || null;
-        logger.info(
-          `[downstream] ${clientId} updatePlugin requested requestId=${requestId || "n/a"}`,
-        );
-        runPluginUpdate()
-          .then((result) => {
-            if (ws.readyState !== WebSocket.OPEN) return;
-            const payload = { type: APP_PROTOCOL.updatePluginResult };
-            if (requestId) payload.requestId = requestId;
-            if (result && result.ok === true) {
-              payload.ok = true;
-            } else {
-              payload.ok = false;
-              if (result && typeof result.reason === "string") {
-                payload.reason = result.reason;
-              }
-              if (result && typeof result.exitCode === "number") {
-                payload.exitCode = result.exitCode;
-              }
-              if (result && typeof result.stderrTail === "string" && result.stderrTail.length > 0) {
-                payload.stderrTail = result.stderrTail;
-              }
-            }
-            sendMessageToClient(clientId, ws, JSON.stringify(payload));
-          })
-          .catch((err) => {
-            logger.error(
-              `[downstream] ${clientId} updatePlugin threw: ${err && err.message ? err.message : err}`,
-            );
-            if (ws.readyState !== WebSocket.OPEN) return;
-            const payload = {
-              type: APP_PROTOCOL.updatePluginResult,
-              ok: false,
-              reason: "spawn_failed",
-            };
-            if (requestId) payload.requestId = requestId;
-            sendMessageToClient(clientId, ws, JSON.stringify(payload));
-          });
-        return;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.restartGateway) {
-        if (!runGatewayRestart) {
-          logger.warn(
-            `[downstream] ${clientId} restartGateway requested but no runGatewayRestart is configured`,
-          );
-          return;
-        }
-        const requestId =
-          parseOptionalTrimmedString(parsed.requestId) || null;
-        logger.info(
-          `[downstream] ${clientId} restartGateway requested requestId=${requestId || "n/a"}`,
-        );
-        runGatewayRestart()
-          .then((result) => {
-            if (ws.readyState !== WebSocket.OPEN) return;
-            const payload = {
-              type: APP_PROTOCOL.restartGatewayAck,
-              ok: !!(result && result.ok),
-              started: !!(result && result.started),
-            };
-            if (requestId) payload.requestId = requestId;
-            if (result && typeof result.reason === "string") {
-              payload.reason = result.reason;
-            }
-            sendMessageToClient(clientId, ws, JSON.stringify(payload));
-          })
-          .catch((err) => {
-            logger.error(
-              `[downstream] ${clientId} restartGateway threw: ${err && err.message ? err.message : err}`,
-            );
-            if (ws.readyState !== WebSocket.OPEN) return;
-            const payload = {
-              type: APP_PROTOCOL.restartGatewayAck,
-              ok: false,
-              started: false,
-              reason: "spawn_failed",
-            };
-            if (requestId) payload.requestId = requestId;
-            sendMessageToClient(clientId, ws, JSON.stringify(payload));
-          });
-        return;
-      }
-
-      if (parsed && parsed.type === "ocuclaw.session.pinned.set") {
-        if (!sessionService) {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "session_service_unavailable" }),
-            );
-          }
-          return;
-        }
-        const sessionKey = typeof parsed.sessionKey === "string" ? parsed.sessionKey : "";
-        const pinned = parsed.pinned;
-        const kind = parsed.kind;
-        if (
-          !sessionKey ||
-          typeof pinned !== "boolean" ||
-          (kind !== "ocuclaw" && kind !== "evenai")
-        ) {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "invalid_session_pin_request" }),
-            );
-          }
-          return;
-        }
-        const result = sessionService.setSessionPinned(kind, sessionKey, pinned);
-        if (!result.ok && result.reason === "cap") {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "pin_cap_reached" }),
-            );
-          }
-          return;
-        }
-        if (!result.ok) {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "invalid_session_pin_request" }),
-            );
-          }
-          return;
-        }
-        if (typeof sessionService.broadcastSessionsForKind === "function") {
-          Promise.resolve(sessionService.broadcastSessionsForKind(kind)).catch((err) => {
-            logger.error(
-              `[downstream] broadcastSessionsForKind failed: ${err && err.message ? err.message : err}`,
-            );
-          });
-        }
-        return;
-      }
-
-      if (parsed && parsed.type === "ocuclaw.session.delete") {
-        if (!sessionService) {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "session_service_unavailable" }),
-            );
-          }
-          return;
-        }
-        const sessionKeys = Array.isArray(parsed.sessionKeys) ? parsed.sessionKeys : null;
-        const kind = parsed.kind;
-        const switchBeforeDelete = parsed.switchBeforeDelete === true;
-        if (
-          !sessionKeys ||
-          sessionKeys.length === 0 ||
-          sessionKeys.some((k) => typeof k !== "string" || !k) ||
-          (kind !== "ocuclaw" && kind !== "evenai")
-        ) {
-          if (ws.readyState === WebSocket.OPEN) {
-            sendMessageToClient(
-              clientId,
-              ws,
-              JSON.stringify({ type: "error", error: "invalid_session_delete_request" }),
-            );
-          }
-          return;
-        }
-        const action = switchBeforeDelete
-          ? sessionService.switchAndDeleteSessions(kind, sessionKeys)
-          : sessionService.deleteSessions(kind, sessionKeys);
-        Promise.resolve(action)
-          .then(() => {
-            if (typeof sessionService.broadcastSessionsForKind === "function") {
-              return sessionService.broadcastSessionsForKind(kind);
-            }
-            return null;
-          })
-          .catch((err) => {
-            logger.error(
-              `[downstream] session.delete pipeline failed: ${err && err.message ? err.message : err}`,
-            );
-          });
-        return;
-      }
-
-      if (parsed && parsed.type === APP_PROTOCOL.avatarFetch) {
-        if (state.selectedVersion !== "v2") return;
-        const requestedAgentName =
-          typeof parsed.agentName === "string" ? parsed.agentName : null;
-        const requestedHash =
-          typeof parsed.hash === "string" && /^[0-9a-f]{64}$/.test(parsed.hash)
-            ? parsed.hash
-            : null;
-        if (!requestedAgentName || !requestedHash) {
-          // Malformed request — silently drop. The WebUI guards against this.
-          return;
-        }
-        const dataUri = getAgentAvatarDataUriByHash(requestedHash);
-        const payload = {
-          type: APP_PROTOCOL.avatarBlob,
-          agentName: requestedAgentName,
-          hash: requestedHash,
-          dataUri: dataUri || null,
-        };
-        if (ws.readyState === WebSocket.OPEN) {
-          sendMessageToClient(clientId, ws, JSON.stringify(payload));
-        }
-        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);
-      clientReadinessSnapshotState.delete(clientId);
-      clearPendingReadinessProbesForClient(clientId);
-      clearPendingAutomationStateRequestsForClient(clientId);
-      nudgeController.deleteClient(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 sendUnicastResult(senderId, unicast) {
-    const frames = Array.isArray(unicast) ? unicast : [unicast];
-    const ws = clients.get(senderId);
-    if (!ws || ws.readyState !== WebSocket.OPEN) return;
-    for (const frame of frames) {
-      if (typeof frame === "string") {
-        sendMessageToClient(senderId, ws, frame);
-      }
-    }
-  }
-
-  function processResult(senderId, result) {
-    if (result === null || result === undefined) {
-      return;
-    }
-
-    if (typeof result.then === "function") {
-      pendingHandlerPromiseCount += 1;
-      if (relayHealth && typeof relayHealth.emitQueueDepth === "function") {
-        relayHealth.emitQueueDepth({
-          pendingHandlerPromises: pendingHandlerPromiseCount,
-        });
-      }
-      result.then(
-        (resolved) => {
-          pendingHandlerPromiseCount = Math.max(0, pendingHandlerPromiseCount - 1);
-          processResult(senderId, resolved);
-        },
-        (err) => {
-          pendingHandlerPromiseCount = Math.max(0, pendingHandlerPromiseCount - 1);
-          logger.error(
-            `[downstream] Error processing message from ${senderId}:`,
-            err,
-          );
-        },
-      );
-      return;
-    }
-
-    if (result.unicast) {
-      sendUnicastResult(senderId, result.unicast);
-    }
-
-    if (result.followup && typeof result.followup.then === "function") {
-      processResult(senderId, result.followup);
-    }
-
-    if (result.readinessProbe) {
-      const requestId = parseOptionalTrimmedString(
-        result.readinessProbe.requestId,
-      );
-      const targetClientId = parseOptionalTrimmedString(
-        result.readinessProbe.targetClientId,
-      );
-      const message =
-        typeof result.readinessProbe.message === "string"
-          ? result.readinessProbe.message
-          : null;
-      const targetWs = targetClientId ? clients.get(targetClientId) : null;
-      if (
-        !requestId ||
-        !targetClientId ||
-        !message ||
-        !targetWs ||
-        targetWs.readyState !== WebSocket.OPEN ||
-        !isAppClient(targetClientId)
-      ) {
-        const requesterWs = clients.get(senderId);
-        if (
-          requesterWs &&
-          requesterWs.readyState === WebSocket.OPEN &&
-          handler &&
-          typeof handler.formatReadinessProbeAck === "function"
-        ) {
-          sendMessageToClient(
-            senderId,
-            requesterWs,
-            handler.formatReadinessProbeAck({
-              ok: false,
-              requestId,
-              reasonCode: "no_downstream_client",
-              message: "No downstream app client connected",
-            }),
-          );
-        }
-      } else {
-        pendingReadinessProbeRequests.set(requestId, {
-          requesterClientId: senderId,
-          targetClientId,
-          createdAtMs: Date.now(),
-        });
-        sendMessageToClient(targetClientId, targetWs, message);
-      }
-    }
-
-    if (result.automationStateRequest) {
-      const requestId = parseOptionalTrimmedString(
-        result.automationStateRequest.requestId,
-      );
-      const targetClientId = parseOptionalTrimmedString(
-        result.automationStateRequest.targetClientId,
-      );
-      const message =
-        typeof result.automationStateRequest.message === "string"
-          ? result.automationStateRequest.message
-          : null;
-      const targetWs = targetClientId ? clients.get(targetClientId) : null;
-      if (
-        !requestId ||
-        !targetClientId ||
-        !message ||
-        !targetWs ||
-        targetWs.readyState !== WebSocket.OPEN ||
-        !isAppClient(targetClientId)
-      ) {
-        const requesterWs = clients.get(senderId);
-        if (
-          requesterWs &&
-          requesterWs.readyState === WebSocket.OPEN &&
-          handler &&
-          typeof handler.formatAutomationStateSnapshot === "function"
-        ) {
-          sendMessageToClient(
-            senderId,
-            requesterWs,
-            handler.formatAutomationStateSnapshot({
-              ok: false,
-              requestId,
-              reasonCode: "snapshot_unavailable",
-              message: "Automation state snapshot is unavailable",
-            }),
-          );
-        }
-      } else {
-        pendingAutomationStateRequests.set(requestId, {
-          requesterClientId: senderId,
-          targetClientId,
-          createdAtMs: Date.now(),
-          expiryTimer: setTimeout(
-            () => expirePendingAutomationStateRequest(requestId),
-            AUTOMATION_STATE_REPLY_TIMEOUT_MS,
-          ),
-        });
-        sendMessageToClient(targetClientId, targetWs, message);
-      }
-    }
-
-    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, messageType);
-        if (
-          messageType === "pages" ||
-          messageType === "status" ||
-          messageType === APP_PROTOCOL.pages ||
-          messageType === APP_PROTOCOL.status
-        ) {
-          markClientSyncedForType(clientId, messageType);
-        }
-      }
-    }
-    nudgeController.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, messageType);
-      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, sessionKey = null) {
-    return countConnectedAppClients(excludeClientId, sessionKey);
-  }
-
-  function getReadinessSnapshot() {
-    const clientsOut = [];
-    let latestUpdatedAtMs = null;
-    for (const [clientId, ws] of clients) {
-      if (!ws || ws.readyState !== WebSocket.OPEN) {
-        continue;
-      }
-      if (!isAppClient(clientId)) {
-        continue;
-      }
-      const entry = buildReadinessClientEntry(clientId);
-      clientsOut.push(entry);
-      const updatedAtMs =
-        entry &&
-        entry.readinessSnapshot &&
-        Number.isFinite(entry.readinessSnapshot.updatedAtMs)
-          ? entry.readinessSnapshot.updatedAtMs
-          : null;
-      if (updatedAtMs !== null && (latestUpdatedAtMs === null || updatedAtMs > latestUpdatedAtMs)) {
-        latestUpdatedAtMs = updatedAtMs;
-      }
-    }
-    clientsOut.sort((left, right) => String(left.clientId).localeCompare(String(right.clientId)));
-    return {
-      connectedClientCount: clientsOut.length,
-      fanoutRecipientCount: clientsOut.length,
-      updatedAtMs: latestUpdatedAtMs,
-      clients: clientsOut,
-    };
-  }
-
-  /**
-   * 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();
-      nudgeController.clear();
-      clientReadinessSnapshotState.clear();
-      pendingReadinessProbeRequests.clear();
-      for (const [, pending] of pendingAutomationStateRequests) {
-        if (pending && pending.expiryTimer) clearTimeout(pending.expiryTimer);
-      }
-      pendingAutomationStateRequests.clear();
-      for (const [, ws] of clients) {
-        ws.close();
-      }
-      clients.clear();
-      wss.close(() => resolve());
-    });
-  }
-
-  return {
-    broadcast,
-    unicast,
-    getClientIds,
-    getConnectedAppCount,
-    getReadinessSnapshot,
-    closeConnectedAppClients,
-    getClientNudgeState(clientId) {
-      return nudgeController.getClientState(clientId);
-    },
-    close,
-    get httpServer() {
-      return opts.httpServer || null;
-    },
-    /** Underlying WebSocket.Server (for reading address, etc.) */
-    get wss() {
-      return wss;
-    },
-  };
-}
-
-export { createDownstreamServer };