ocuclaw 1.2.4 → 1.3.1

package/dist/runtime/relay-worker-approval-replay-cache.js

@@ -0,0 +1,68 @@
+const DEFAULT_TTL_MS = 30_000;
+const DEFAULT_MAX_ENTRIES = 64;
+
+function normalizeNonNegativeInteger(value, fallback) {
+  if (!Number.isFinite(Number(value))) return fallback;
+  return Math.max(0, Math.floor(Number(value)));
+}
+
+export function createApprovalReplayCache(options = {}) {
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const ttlMs = normalizeNonNegativeInteger(options.ttlMs, DEFAULT_TTL_MS);
+  const maxEntries = normalizeNonNegativeInteger(options.maxEntries, DEFAULT_MAX_ENTRIES);
+  const entries = new Map(); // id -> { frame, cachedAtMs, frameExpiresAtMs }
+
+  function nowMs() {
+    return normalizeNonNegativeInteger(now(), Date.now());
+  }
+
+  function isStale(entry, atMs) {
+    if (ttlMs > 0 && atMs - entry.cachedAtMs > ttlMs) return true;
+    if (entry.frameExpiresAtMs > 0 && entry.frameExpiresAtMs <= atMs) return true;
+    return false;
+  }
+
+  function set(id, frame, frameExpiresAtMs) {
+    if (typeof id !== "string" || !id.trim()) return;
+    const key = id.trim();
+    entries.delete(key);
+    entries.set(key, {
+      frame,
+      cachedAtMs: nowMs(),
+      frameExpiresAtMs: normalizeNonNegativeInteger(frameExpiresAtMs, 0),
+    });
+    while (maxEntries > 0 && entries.size > maxEntries) {
+      const oldest = entries.keys().next();
+      if (oldest.done) break;
+      entries.delete(oldest.value);
+    }
+  }
+
+  function remove(id) {
+    if (typeof id !== "string") return false;
+    return entries.delete(id.trim());
+  }
+
+  function activeFrames() {
+    const atMs = nowMs();
+    const frames = [];
+    for (const [key, entry] of entries) {
+      if (isStale(entry, atMs)) {
+        entries.delete(key);
+        continue;
+      }
+      frames.push(entry.frame);
+    }
+    return frames;
+  }
+
+  function size() {
+    return entries.size;
+  }
+
+  function clear() {
+    entries.clear();
+  }
+
+  return { set, remove, activeFrames, size, clear };
+}

package/dist/runtime/relay-worker-entry.js

@@ -0,0 +1,32 @@
+import { parentPort } from "node:worker_threads";
+import { createRelayWorkerTransport } from "./relay-worker-transport.js";
+
+if (!parentPort) {
+  throw new Error("relay worker entry requires parentPort");
+}
+
+const transport = createRelayWorkerTransport({
+  postToMain(message) {
+    parentPort.postMessage(message);
+  },
+});
+
+parentPort.on("message", async (message) => {
+  try {
+    if (message && message.kind === "manifest") {
+      await transport.start(message);
+      return;
+    }
+    if (message && message.kind === "shutdown") {
+      await transport.close();
+      parentPort.postMessage({ kind: "worker.closed" });
+      return;
+    }
+    transport.handleMainMessage(message);
+  } catch (err) {
+    parentPort.postMessage({
+      kind: "worker.error",
+      message: err && err.message ? err.message : String(err),
+    });
+  }
+});

package/dist/runtime/relay-worker-health.js

@@ -0,0 +1,272 @@
+import { formatWorkerHealth } from "./relay-worker-protocol.js";
+
+const DEFAULT_THRESHOLDS = Object.freeze({
+  mainDelayedThresholdMs: 2_000,
+  mainRecoveredThresholdMs: 800,
+  emitHeartbeatMs: 5_000,
+  loopLagDegradedP95Ms: 250,
+  loopLagRecoveredP95Ms: 100,
+});
+
+const MESSAGE_SEND_DEGRADED_DEPTH = 32;
+
+function normalizeNonNegativeInteger(value, fallback) {
+  if (!Number.isFinite(Number(value))) return fallback;
+  return Math.max(0, Math.floor(Number(value)));
+}
+
+function normalizeOptionalNonNegativeInteger(value) {
+  if (value === null || value === undefined) return null;
+  if (!Number.isFinite(Number(value))) return null;
+  return Math.max(0, Math.floor(Number(value)));
+}
+
+function normalizeThresholds(value = {}) {
+  return {
+    mainDelayedThresholdMs: normalizeNonNegativeInteger(
+      value.mainDelayedThresholdMs,
+      DEFAULT_THRESHOLDS.mainDelayedThresholdMs,
+    ),
+    mainRecoveredThresholdMs: normalizeNonNegativeInteger(
+      value.mainRecoveredThresholdMs,
+      DEFAULT_THRESHOLDS.mainRecoveredThresholdMs,
+    ),
+    emitHeartbeatMs: normalizeNonNegativeInteger(
+      value.emitHeartbeatMs,
+      DEFAULT_THRESHOLDS.emitHeartbeatMs,
+    ),
+    loopLagDegradedP95Ms: normalizeNonNegativeInteger(
+      value.loopLagDegradedP95Ms,
+      DEFAULT_THRESHOLDS.loopLagDegradedP95Ms,
+    ),
+    loopLagRecoveredP95Ms: normalizeNonNegativeInteger(
+      value.loopLagRecoveredP95Ms,
+      DEFAULT_THRESHOLDS.loopLagRecoveredP95Ms,
+    ),
+  };
+}
+
+function normalizeQueueDepthByClass(value) {
+  return {
+    "message.send": normalizeNonNegativeInteger(
+      value && value["message.send"],
+      0,
+    ),
+  };
+}
+
+export function createRelayWorkerHealthMonitor(options = {}) {
+  const now = typeof options.now === "function" ? options.now : () => Date.now();
+  const emitFrame = typeof options.emitFrame === "function" ? options.emitFrame : () => {};
+  const emitDebug = typeof options.emitDebug === "function" ? options.emitDebug : () => {};
+  const workerEpoch = normalizeNonNegativeInteger(options.workerEpoch, 0);
+  const thresholds = normalizeThresholds(options.thresholds);
+
+  let status = "main_disconnected";
+  let lastStatusEmitAtMs = null;
+  let lastMainHeartbeatAtMs = null;
+  let lastMainFrameAtMs = null;
+  let lastMainStatusAtMs = null;
+  let cachedPagesRevision = null;
+  let cachedStatusRevision = null;
+  let workerMainQueueDepth = 0;
+  let workerMainPostLatencyMs = null;
+  let workerQueueDepthByClass = normalizeQueueDepthByClass(null);
+  let loopLagP95Ms = null;
+  let sendBufferHighWaterClients = 0;
+
+  function nowMs() {
+    return normalizeNonNegativeInteger(now(), Date.now());
+  }
+
+  function ageFrom(atMs, currentMs) {
+    if (atMs === null) return null;
+    return Math.max(0, currentMs - atMs);
+  }
+
+  function latestMainActivityAtMs() {
+    if (lastMainHeartbeatAtMs === null) return lastMainFrameAtMs;
+    if (lastMainFrameAtMs === null) return lastMainHeartbeatAtMs;
+    return Math.max(lastMainHeartbeatAtMs, lastMainFrameAtMs);
+  }
+
+  function updateCachedRevisions(data = {}, atMs = nowMs()) {
+    const pagesRevision = normalizeOptionalNonNegativeInteger(data.cachedPagesRevision);
+    const statusRevision = normalizeOptionalNonNegativeInteger(data.cachedStatusRevision);
+    if (pagesRevision !== null) {
+      cachedPagesRevision = pagesRevision;
+    }
+    if (statusRevision !== null) {
+      cachedStatusRevision = statusRevision;
+      lastMainStatusAtMs = normalizeOptionalNonNegativeInteger(data.lastMainStatusAtMs) ?? atMs;
+    } else if (data.lastMainStatusAtMs !== undefined) {
+      lastMainStatusAtMs = normalizeOptionalNonNegativeInteger(data.lastMainStatusAtMs);
+    }
+  }
+
+  function buildFrame(nextStatus) {
+    const atMs = nowMs();
+    return formatWorkerHealth({
+      workerEpoch,
+      workerStatus: nextStatus,
+      mainFrameAgeMs: ageFrom(lastMainFrameAtMs, atMs),
+      mainHeartbeatAgeMs: ageFrom(lastMainHeartbeatAtMs, atMs),
+      workerMainQueueDepth,
+      workerMainPostLatencyMs,
+      workerQueueDepthByClass,
+      cachedPagesRevision,
+      cachedStatusRevision,
+      lastMainStatusAtMs,
+      backpressure: {
+        loopLagP95Ms,
+        sendBufferHighWaterClients,
+        messageSendQueueDepth: workerQueueDepthByClass["message.send"],
+      },
+    });
+  }
+
+  function shouldEmitHeartbeat(atMs) {
+    if (lastStatusEmitAtMs === null) return true;
+    return thresholds.emitHeartbeatMs > 0 &&
+      atMs - lastStatusEmitAtMs >= thresholds.emitHeartbeatMs;
+  }
+
+  function setStatus(nextStatus, force = false) {
+    const atMs = nowMs();
+    const previousStatus = status;
+    const transitioned = nextStatus !== previousStatus;
+
+    if (!transitioned && !force && !shouldEmitHeartbeat(atMs)) {
+      return status;
+    }
+
+    status = nextStatus;
+    emitFrame(buildFrame(nextStatus));
+    lastStatusEmitAtMs = atMs;
+
+    if (transitioned) {
+      emitDebug("worker_health_transition", "info", {
+        from: previousStatus,
+        to: nextStatus,
+        workerEpoch,
+        mainFrameAgeMs: ageFrom(lastMainFrameAtMs, atMs),
+        mainHeartbeatAgeMs: ageFrom(lastMainHeartbeatAtMs, atMs),
+        workerMainQueueDepth,
+        workerQueueDepthByClass,
+      });
+    }
+
+    return status;
+  }
+
+  function isDegraded() {
+    if (workerQueueDepthByClass["message.send"] >= MESSAGE_SEND_DEGRADED_DEPTH) {
+      return true;
+    }
+    if (sendBufferHighWaterClients >= 1) {
+      return true;
+    }
+    if (loopLagP95Ms !== null) {
+      // Hysteresis: enter at the degraded threshold; once degraded, stay degraded
+      // until lag drops below the (lower) recovered threshold.
+      const enterThreshold =
+        status === "degraded"
+          ? thresholds.loopLagRecoveredP95Ms
+          : thresholds.loopLagDegradedP95Ms;
+      if (loopLagP95Ms >= enterThreshold) return true;
+    }
+    return false;
+  }
+
+  function computeStatus() {
+    // Precedence is deliberate: `degraded` (worker strain) is reported before
+    // `main_disconnected`. On a live worker the two cannot co-occur — live
+    // message.send queue depth tops at 31 (enqueue rejects at the cap before set)
+    // and `main_disconnected` is only the pre-first-heartbeat boot state — so this
+    // order is never observably wrong. Any future reorder is conditional on BOTH a
+    // product-copy reason to prefer a "waiting" label during a disconnect AND a
+    // degraded condition becoming live-reachable, and must ship with a degraded
+    // secondary-text line + distinct badge in the phone UI.
+    if (isDegraded()) {
+      return "degraded";
+    }
+    const mainActivityAtMs = latestMainActivityAtMs();
+    if (mainActivityAtMs === null) {
+      return "main_disconnected";
+    }
+
+    const mainActivityAgeMs = ageFrom(mainActivityAtMs, nowMs());
+    if (status === "main_delayed") {
+      return mainActivityAgeMs > thresholds.mainRecoveredThresholdMs
+        ? "main_delayed"
+        : "ready";
+    }
+    return mainActivityAgeMs >= thresholds.mainDelayedThresholdMs
+      ? "main_delayed"
+      : "ready";
+  }
+
+  function recordMainHeartbeat(data = {}) {
+    const atMs = nowMs();
+    lastMainHeartbeatAtMs = atMs;
+    updateCachedRevisions(data, atMs);
+    return setStatus(computeStatus(), true);
+  }
+
+  function recordMainFrame(data = {}) {
+    const atMs = nowMs();
+    lastMainFrameAtMs = atMs;
+    updateCachedRevisions(data, atMs);
+    return setStatus(computeStatus());
+  }
+
+  function updateQueueDepth(nextDepthByClass = {}) {
+    workerQueueDepthByClass = normalizeQueueDepthByClass(nextDepthByClass);
+    return status;
+  }
+
+  function updateLoopLagP95Ms(value) {
+    loopLagP95Ms = normalizeOptionalNonNegativeInteger(value);
+    return status;
+  }
+
+  function updateSendBufferHighWaterClients(value) {
+    sendBufferHighWaterClients = normalizeNonNegativeInteger(value, 0);
+    return status;
+  }
+
+  function updateWorkerMainQueueDepth(value) {
+    workerMainQueueDepth = normalizeNonNegativeInteger(value, 0);
+    return status;
+  }
+
+  function updateWorkerMainPostLatencyMs(value) {
+    workerMainPostLatencyMs = normalizeOptionalNonNegativeInteger(value);
+    return status;
+  }
+
+  function markRestarting() {
+    return setStatus("restarting", true);
+  }
+
+  function sample() {
+    return setStatus(computeStatus());
+  }
+
+  function currentStatus() {
+    return status;
+  }
+
+  return {
+    recordMainHeartbeat,
+    recordMainFrame,
+    updateQueueDepth,
+    updateLoopLagP95Ms,
+    updateSendBufferHighWaterClients,
+    updateWorkerMainQueueDepth,
+    updateWorkerMainPostLatencyMs,
+    markRestarting,
+    sample,
+    currentStatus,
+  };
+}

package/dist/runtime/relay-worker-protocol.js

@@ -0,0 +1,281 @@
+export const APP_PROTOCOL = Object.freeze({
+  messageSend: "ocuclaw.message.send",
+  messageSendAck: "ocuclaw.message.send.ack",
+  operationReceived: "ocuclaw.operation.received",
+  workerOperationReceived: "ocuclaw.worker.operation.received",
+  workerHealth: "ocuclaw.worker.health",
+  protocolHelloAck: "protocolHelloAck",
+  resumeAck: "ocuclaw.sync.resume.ack",
+  pages: "ocuclaw.view.pages.snapshot",
+  status: "ocuclaw.runtime.status",
+  debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
+  avatarFetch: "ocuclaw.avatar.fetch",
+  avatarBlob: "ocuclaw.avatar.blob",
+  readinessSnapshot: "ocuclaw.readiness.snapshot",
+  readinessProbeRequest: "ocuclaw.readiness.probe.request",
+  readinessProbeAck: "ocuclaw.readiness.probe.ack",
+  automationStateGet: "ocuclaw.automation.state.get",
+  automationStateSnapshot: "ocuclaw.automation.state.snapshot",
+  approvalRequest: "ocuclaw.approval.request",
+  approvalResolved: "ocuclaw.approval.resolved",
+  sessionContextSnapshot: "ocuclaw.session.context.snapshot",
+  sessionCompact: "ocuclaw.session.compact",
+  sessionCompactAck: "ocuclaw.session.compact.ack",
+  visibility: "visibility",
+});
+
+export const WORKER_FEATURES = Object.freeze([
+  "worker-health",
+  "worker-receipts",
+  "worker-resume-metadata",
+  "message-send-worker-queue",
+]);
+
+export const DEFAULT_WORKER_QUEUE_CAPS = Object.freeze({
+  messageSendMaxEntries: 32,
+  messageSendTtlMs: 30_000,
+  retainedFinalTtlMs: 30_000,
+  oldEpochPendingHardCapMs: 90_000,
+});
+
+export const DEFAULT_WORKER_HEALTH_THRESHOLDS = Object.freeze({
+  mainDelayedThresholdMs: 2_000,
+  mainRecoveredThresholdMs: 800,
+  mainStaleResumeThresholdMs: 5_000,
+  heartbeatIntervalMs: 1_000,
+  emitHeartbeatMs: 5_000,
+  loopLagDegradedP95Ms: 250,
+  loopLagRecoveredP95Ms: 100,
+});
+
+export const DEFAULT_NUDGE_THRESHOLDS = Object.freeze({
+  nudgeActiveIntervalMs: 150,
+  nudgeSlowIntervalMs: 1000,
+  nudgeIdleDeactivateMs: 5000,
+  nudgeHeartbeatIntervalMs: 10000,
+  nudgeHardTimeoutMs: 60000,
+});
+
+export const DEFAULT_WORKER_RPC_LIMITS = Object.freeze({
+  mainRequestTimeoutMs: 5_000,
+  httpRequestTimeoutMs: 60_000,
+  httpMaxBodyBytes: 65_536,
+  httpMaxResponseBytes: 262_144,
+});
+
+const ALLOWED_WORKER_STATUSES = new Set([
+  "ready",
+  "main_delayed",
+  "main_disconnected",
+  "restarting",
+  "degraded",
+]);
+const ALLOWED_CACHE_STATES = new Set(["fresh", "stale", "empty", "warming"]);
+const WORKER_QUEUE_CLASSES = Object.freeze(["message.send"]);
+
+export function normalizeRequestId(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+export function parseNonNegativeRevision(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string" && value.trim() === "") return null;
+  if (!Number.isFinite(Number(value))) return null;
+  const num = Math.floor(Number(value));
+  return num >= 0 ? num : null;
+}
+
+function parseNonNegativeInteger(value) {
+  return parseNonNegativeRevision(value);
+}
+
+function parseNonNegativeDuration(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string" && value.trim() === "") return null;
+  if (!Number.isFinite(Number(value))) return null;
+  return Math.max(0, Math.floor(Number(value)));
+}
+
+function normalizeWorkerStatus(value) {
+  return ALLOWED_WORKER_STATUSES.has(value) ? value : "ready";
+}
+
+function normalizeCacheState(value) {
+  return ALLOWED_CACHE_STATES.has(value) ? value : null;
+}
+
+function normalizeWorkerQueueDepthByClass(value) {
+  const source = value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : {};
+  const depths = {};
+  for (const className of WORKER_QUEUE_CLASSES) {
+    const parsed = parseNonNegativeInteger(source[className]);
+    depths[className] = parsed === null ? 0 : parsed;
+  }
+  return depths;
+}
+
+function normalizeRequestIdList(value) {
+  if (!Array.isArray(value)) return null;
+  const ids = [];
+  for (const entry of value) {
+    const requestId = normalizeRequestId(entry);
+    if (requestId) {
+      ids.push(requestId);
+    }
+  }
+  return ids;
+}
+
+export function estimateJsonByteLength(value) {
+  return Buffer.byteLength(JSON.stringify(value ?? null), "utf8");
+}
+
+export function parseMessageType(message) {
+  try {
+    const parsed = typeof message === "string" ? JSON.parse(message) : message;
+    return parsed && typeof parsed.type === "string" ? parsed.type : null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeBackpressure(value) {
+  const v = value && typeof value === "object" ? value : {};
+  return {
+    loopLagP95Ms: parseNonNegativeDuration(v.loopLagP95Ms),
+    sendBufferHighWaterClients: parseNonNegativeInteger(v.sendBufferHighWaterClients) ?? 0,
+    messageSendQueueDepth: parseNonNegativeInteger(v.messageSendQueueDepth) ?? 0,
+  };
+}
+
+export function formatWorkerHealth(data = {}) {
+  return JSON.stringify({
+    type: APP_PROTOCOL.workerHealth,
+    workerEpoch: parseNonNegativeInteger(data.workerEpoch) ?? 0,
+    workerStatus: normalizeWorkerStatus(data.workerStatus),
+    mainFrameAgeMs: parseNonNegativeDuration(data.mainFrameAgeMs),
+    mainHeartbeatAgeMs: parseNonNegativeDuration(data.mainHeartbeatAgeMs),
+    workerMainQueueDepth: parseNonNegativeInteger(data.workerMainQueueDepth) ?? 0,
+    workerMainPostLatencyMs: parseNonNegativeDuration(data.workerMainPostLatencyMs),
+    workerQueueDepthByClass: normalizeWorkerQueueDepthByClass(data.workerQueueDepthByClass),
+    cachedPagesRevision: parseNonNegativeRevision(data.cachedPagesRevision),
+    cachedStatusRevision: parseNonNegativeRevision(data.cachedStatusRevision),
+    lastMainStatusAtMs: parseNonNegativeInteger(data.lastMainStatusAtMs),
+    backpressure: normalizeBackpressure(data.backpressure),
+  });
+}
+
+export function formatWorkerOperationReceived(data) {
+  const requestId = normalizeRequestId(data && data.requestId);
+  if (!requestId) throw new Error("worker receipt requires requestId");
+  return JSON.stringify({
+    type: APP_PROTOCOL.workerOperationReceived,
+    requestId,
+    operation: data.operation || "message.send",
+    status: "worker_pending",
+    phase: "worker_received",
+    workerEpoch: parseNonNegativeInteger(data.workerEpoch) ?? 0,
+    receivedAtMs: parseNonNegativeInteger(data.receivedAtMs) ?? Date.now(),
+  });
+}
+
+export function formatMainOperationReceived(data) {
+  const requestId = normalizeRequestId(data && data.requestId);
+  if (!requestId) throw new Error("main receipt requires requestId");
+  return JSON.stringify({
+    type: APP_PROTOCOL.operationReceived,
+    requestId,
+    operation: data.operation || "message.send",
+    status: data.status || "upstream_pending",
+    phase: data.phase || "relay_received",
+    receivedAtMs: parseNonNegativeInteger(data.receivedAtMs) ?? Date.now(),
+  });
+}
+
+export function formatSendAck(requestId, status, error, errorCode) {
+  const id = normalizeRequestId(requestId);
+  const msg = { type: APP_PROTOCOL.messageSendAck, requestId: id, status };
+  if (error !== undefined) msg.error = error;
+  if (errorCode !== undefined) msg.errorCode = errorCode;
+  return JSON.stringify(msg);
+}
+
+export function formatWorkerQueueTimeoutAck(requestId) {
+  return formatSendAck(
+    requestId,
+    "rejected",
+    "OpenClaw did not accept the message before the relay worker queue timeout.",
+    "worker_queue_timeout",
+  );
+}
+
+export function formatWorkerRestartUncertainAck(requestId) {
+  return formatSendAck(
+    requestId,
+    "rejected",
+    "The relay worker restarted before OpenClaw accepted the message. Retry may resend the message.",
+    "worker_restarted_before_main_accept",
+  );
+}
+
+export function formatProtocolHelloAck(payload = {}) {
+  const ack = {
+    type: APP_PROTOCOL.protocolHelloAck,
+    protocolVersion: payload.protocolVersion || "v2",
+    supportedProtocolVersions: Array.isArray(payload.supportedProtocolVersions)
+      ? payload.supportedProtocolVersions
+      : ["v2"],
+    reason: payload.reason || null,
+    deprecatedV1: false,
+  };
+  if (typeof payload.pluginVersion === "string" && payload.pluginVersion) ack.pluginVersion = payload.pluginVersion;
+  if (typeof payload.requiresClientVersion === "string" && payload.requiresClientVersion) ack.requiresClientVersion = payload.requiresClientVersion;
+  if (typeof payload.pluginId === "string" && payload.pluginId) ack.pluginId = payload.pluginId;
+  const workerEpoch = parseNonNegativeInteger(payload.workerEpoch);
+  if (workerEpoch !== null) ack.workerEpoch = workerEpoch;
+  if (Array.isArray(payload.workerFeatures)) ack.workerFeatures = payload.workerFeatures;
+  return JSON.stringify(ack);
+}
+
+export function formatResumeAck(payload = {}) {
+  const msg = {
+    type: APP_PROTOCOL.resumeAck,
+    reason: payload.reason || null,
+    sentPages: !!payload.sentPages,
+    sentStatus: !!payload.sentStatus,
+    sentApprovals: parseNonNegativeInteger(payload.sentApprovals) ?? 0,
+    pagesRevision: parseNonNegativeRevision(payload.pagesRevision),
+    statusRevision: parseNonNegativeRevision(payload.statusRevision),
+  };
+  for (const key of [
+    "workerEpoch",
+    "previousWorkerEpoch",
+    "cachedPagesRevision",
+    "cachedStatusRevision",
+  ]) {
+    const parsed = parseNonNegativeRevision(payload[key]);
+    if (parsed !== null) msg[key] = parsed;
+  }
+  for (const key of ["workerRestarted", "mainStale", "resumeProvisional"]) {
+    if (payload[key] !== undefined) msg[key] = !!payload[key];
+  }
+  const cacheState = normalizeCacheState(payload.cacheState);
+  if (cacheState) msg.cacheState = cacheState;
+  const workerOnlyPendingRequestIds = normalizeRequestIdList(
+    payload.workerOnlyPendingRequestIds,
+  );
+  if (workerOnlyPendingRequestIds) {
+    msg.workerOnlyPendingRequestIds = workerOnlyPendingRequestIds;
+  }
+  const unresolvedWorkerPendingRequestIds = normalizeRequestIdList(
+    payload.unresolvedWorkerPendingRequestIds,
+  );
+  if (unresolvedWorkerPendingRequestIds) {
+    msg.unresolvedWorkerPendingRequestIds = unresolvedWorkerPendingRequestIds;
+  }
+  return JSON.stringify(msg);
+}