ocuclaw 1.2.4 → 1.3.1

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

@@ -0,0 +1,172 @@
+import { PerformanceObserver, monitorEventLoopDelay } from "node:perf_hooks";
+
+const LOW_LAG_SAMPLE_THRESHOLD_MS = 50;
+const LOW_LAG_HEARTBEAT_MS = 60_000;
+const SPIKE_BUCKETS_MS = [250, 1_000, 5_000, 10_000];
+const DEFAULT_SEND_BUFFER_HIGH_WATER_BYTES = 262_144;
+
+export function classifyFrameForRelayHealth(messageType) {
+  if (
+    messageType === "ping" ||
+    messageType === "pong" ||
+    messageType === "protocolHelloAck" ||
+    messageType === "ocuclaw.sync.resume.ack" ||
+    messageType === "ocuclaw.worker.health"
+  ) {
+    return "transport-control";
+  }
+  if (
+    messageType === "ocuclaw.operation.received" ||
+    messageType === "ocuclaw.worker.operation.received" ||
+    messageType === "ocuclaw.relay.busy"
+  ) {
+    return "operation-control";
+  }
+  if (
+    messageType === "ocuclaw.message.send.ack" ||
+    messageType === "ocuclaw.approval.resolve.ack"
+  ) {
+    return "transactional";
+  }
+  if (
+    messageType === "ocuclaw.session.switch.applied" ||
+    messageType === "ocuclaw.session.config.set.ack" ||
+    messageType === "ocuclaw.evenai.settings.set.ack" ||
+    messageType === "ocuclaw.settings.set.ack"
+  ) {
+    return "latest-mutation";
+  }
+  if (
+    messageType === "ocuclaw.runtime.status" ||
+    messageType === "ocuclaw.session.list.result" ||
+    messageType === "ocuclaw.provider.usage.snapshot" ||
+    messageType === "ocuclaw.model.catalog.snapshot" ||
+    messageType === "ocuclaw.skills.catalog.snapshot"
+  ) {
+    return "coalescable-read";
+  }
+  return "best-effort";
+}
+
+export function createRelayHealthMonitor(options) {
+  const now = options.now || Date.now;
+  const setIntervalFn = options.setIntervalFn || setInterval;
+  const clearIntervalFn = options.clearIntervalFn || clearInterval;
+  const sampleIntervalMs = options.sampleIntervalMs || 1_000;
+  const sendBufferHighWaterBytes =
+    options.sendBufferHighWaterBytes || DEFAULT_SEND_BUFFER_HIGH_WATER_BYTES;
+  let intervalId = null;
+  let delayMonitor = null;
+  let gcObserver = null;
+  let lastLowLagEmitAtMs = null;
+  const emittedSpikeBuckets = new Set();
+
+  function defaultSampleEventLoopDelay() {
+    if (!delayMonitor) {
+      return { p50Ms: 0, p95Ms: 0, maxMs: 0, sampleCount: 0 };
+    }
+    const sample = {
+      p50Ms: delayMonitor.percentile(50) / 1_000_000,
+      p95Ms: delayMonitor.percentile(95) / 1_000_000,
+      maxMs: delayMonitor.max / 1_000_000,
+      sampleCount: Number(delayMonitor.count || 0),
+    };
+    delayMonitor.reset();
+    return sample;
+  }
+
+  function emitLagSample() {
+    const sample = options.sampleEventLoopDelay
+      ? options.sampleEventLoopDelay()
+      : defaultSampleEventLoopDelay();
+    const nowMs = now();
+    const shouldEmitLowLagHeartbeat =
+      lastLowLagEmitAtMs === null || nowMs - lastLowLagEmitAtMs >= LOW_LAG_HEARTBEAT_MS;
+    const shouldEmitSample =
+      sample.maxMs >= LOW_LAG_SAMPLE_THRESHOLD_MS || shouldEmitLowLagHeartbeat;
+    if (shouldEmitSample) {
+      if (sample.maxMs < LOW_LAG_SAMPLE_THRESHOLD_MS) {
+        lastLowLagEmitAtMs = nowMs;
+      }
+      options.emitDebug("event_loop_lag_sample", "debug", {
+        p50Ms: Math.round(sample.p50Ms),
+        p95Ms: Math.round(sample.p95Ms),
+        maxMs: Math.round(sample.maxMs),
+        sampleCount: sample.sampleCount,
+        sampleIntervalMs,
+      });
+    }
+    for (const bucketMs of SPIKE_BUCKETS_MS) {
+      if (sample.maxMs >= bucketMs && !emittedSpikeBuckets.has(bucketMs)) {
+        emittedSpikeBuckets.add(bucketMs);
+        options.emitDebug("event_loop_lag_spike", "warn", {
+          bucketMs,
+          maxMs: Math.round(sample.maxMs),
+          p95Ms: Math.round(sample.p95Ms),
+          sampleCount: sample.sampleCount,
+        });
+      }
+    }
+    if (sample.maxMs < SPIKE_BUCKETS_MS[0]) {
+      emittedSpikeBuckets.clear();
+    }
+  }
+
+  function start() {
+    if (intervalId !== null) return;
+    lastLowLagEmitAtMs = now();
+    if (!options.sampleEventLoopDelay) {
+      delayMonitor = monitorEventLoopDelay({ resolution: 50 });
+      delayMonitor.enable();
+    }
+    if (options.observeGc !== false) {
+      gcObserver = new PerformanceObserver((list) => {
+        for (const entry of list.getEntries()) {
+          options.emitDebug("gc_pause", "warn", {
+            durationMs: Math.round(entry.duration),
+            kind: Number(entry.kind || 0),
+          });
+        }
+      });
+      gcObserver.observe({ entryTypes: ["gc"] });
+    }
+    intervalId = setIntervalFn(emitLagSample, sampleIntervalMs);
+  }
+
+  function stop() {
+    if (intervalId !== null) {
+      clearIntervalFn(intervalId);
+      intervalId = null;
+    }
+    if (delayMonitor) {
+      delayMonitor.disable();
+      delayMonitor = null;
+    }
+    if (gcObserver) {
+      gcObserver.disconnect();
+      gcObserver = null;
+    }
+  }
+
+  function observeSendBuffer(params) {
+    if (
+      params.bufferedAmountBytes !== null &&
+      Number.isFinite(params.bufferedAmountBytes) &&
+      params.bufferedAmountBytes >= sendBufferHighWaterBytes
+    ) {
+      options.emitDebug("ws_send_buffer_high_water", "warn", {
+        clientId: params.clientId,
+        messageType: params.messageType,
+        frameClass: classifyFrameForRelayHealth(params.messageType),
+        bufferedAmountBytes: params.bufferedAmountBytes,
+        thresholdBytes: sendBufferHighWaterBytes,
+      });
+    }
+  }
+
+  function emitQueueDepth(snapshot) {
+    options.emitDebug("relay_queue_depth", "debug", snapshot);
+  }
+
+  return { start, stop, observeSendBuffer, emitQueueDepth };
+}

package/dist/runtime/relay-operation-registry.js

@@ -0,0 +1,263 @@
+const SLOW_BUCKETS_MS = [5_000, 10_000, 30_000, 60_000];
+
+export function createRelayOperationRegistry(options) {
+  const now = options.now || Date.now;
+  const retentionMs = options.retentionMs || 90_000;
+  const entriesByRequestId = new Map();
+  const requestIdByRunId = new Map();
+
+  function prune(nowMs = now()) {
+    for (const [requestId, entry] of entriesByRequestId) {
+      if (nowMs - entry.receivedAtMs > retentionMs) {
+        entriesByRequestId.delete(requestId);
+        for (const [runId, mappedRequestId] of requestIdByRunId) {
+          if (mappedRequestId === requestId) {
+            requestIdByRunId.delete(runId);
+          }
+        }
+      }
+    }
+  }
+
+  function receiptFrame(entry) {
+    return JSON.stringify({
+      type: "ocuclaw.operation.received",
+      requestId: entry.requestId,
+      operation: entry.operation,
+      status: "upstream_pending",
+      phase: "relay_received",
+      receivedAtMs: entry.receivedAtMs,
+    });
+  }
+
+  function beginMessageSend(params) {
+    prune();
+    const existing = entriesByRequestId.get(params.requestId);
+    if (existing) {
+      options.emitDebug(
+        "operation_received",
+        "info",
+        {
+          requestId: existing.requestId,
+          operation: existing.operation,
+          class: existing.class,
+          clientId: existing.clientId,
+          sessionKey: existing.sessionKey,
+          duplicate: true,
+          retainedFinal: existing.finalFrame !== null,
+        },
+        { sessionKey: existing.sessionKey },
+      );
+      return {
+        duplicate: true,
+        receipt: receiptFrame(existing),
+        finalFrame: existing.finalFrame,
+        complete: (finalFrame, result = {}) =>
+          complete(existing.requestId, finalFrame, result),
+        fail: (finalFrame, result = {}) =>
+          fail(existing.requestId, finalFrame, result),
+      };
+    }
+
+    const receivedAtMs = now();
+    const entry = {
+      requestId: params.requestId,
+      operation: "message.send",
+      class: "transactional",
+      clientId: params.clientId,
+      sessionKey: params.sessionKey || null,
+      receivedAtMs,
+      startedAtMs: null,
+      upstreamAckAtMs: null,
+      lifecycleStartAtMs: null,
+      firstStreamAtMs: null,
+      completedAtMs: null,
+      finalFrame: null,
+      slowBuckets: new Set(),
+    };
+    entriesByRequestId.set(entry.requestId, entry);
+    options.emitDebug(
+      "operation_received",
+      "info",
+      {
+        requestId: entry.requestId,
+        operation: entry.operation,
+        class: entry.class,
+        clientId: entry.clientId,
+        sessionKey: entry.sessionKey,
+        duplicate: false,
+      },
+      { sessionKey: entry.sessionKey },
+    );
+    return {
+      duplicate: false,
+      receipt: receiptFrame(entry),
+      finalFrame: null,
+      complete: (finalFrame, result = {}) => complete(entry.requestId, finalFrame, result),
+      fail: (finalFrame, result = {}) => fail(entry.requestId, finalFrame, result),
+    };
+  }
+
+  function markStarted(requestId) {
+    const entry = entriesByRequestId.get(requestId);
+    if (!entry || entry.startedAtMs !== null) return;
+    entry.startedAtMs = now();
+    options.emitDebug(
+      "operation_started",
+      "debug",
+      {
+        requestId,
+        operation: entry.operation,
+        class: entry.class,
+        elapsedMs: entry.startedAtMs - entry.receivedAtMs,
+      },
+      { sessionKey: entry.sessionKey },
+    );
+  }
+
+  function markUpstreamAck(requestId, params = {}) {
+    const entry = entriesByRequestId.get(requestId);
+    if (!entry) return;
+    entry.upstreamAckAtMs = now();
+    if (params.runId) requestIdByRunId.set(params.runId, requestId);
+    options.emitDebug(
+      "operation_phase",
+      "debug",
+      {
+        requestId,
+        operation: entry.operation,
+        class: entry.class,
+        phase: "upstream_ack",
+        status: params.status || null,
+        elapsedMs: entry.upstreamAckAtMs - entry.receivedAtMs,
+        upstreamAckMs: entry.upstreamAckAtMs - entry.receivedAtMs,
+      },
+      { sessionKey: entry.sessionKey, runId: params.runId || null },
+    );
+  }
+
+  function markRunPhase(runId, phase) {
+    const requestId = requestIdByRunId.get(runId);
+    if (!requestId) return;
+    const entry = entriesByRequestId.get(requestId);
+    if (!entry) return;
+    const atMs = now();
+    if (phase === "lifecycle_start" && entry.lifecycleStartAtMs === null) {
+      entry.lifecycleStartAtMs = atMs;
+    }
+    if (phase === "first_stream" && entry.firstStreamAtMs === null) {
+      entry.firstStreamAtMs = atMs;
+    }
+    if (phase === "complete") {
+      entry.completedAtMs = atMs;
+    }
+    options.emitDebug(
+      "operation_phase",
+      "debug",
+      {
+        requestId,
+        operation: entry.operation,
+        class: entry.class,
+        phase,
+        elapsedMs: atMs - entry.receivedAtMs,
+        ackToPhaseMs: entry.upstreamAckAtMs ? atMs - entry.upstreamAckAtMs : null,
+        lifecycleStartMs: entry.lifecycleStartAtMs
+          ? entry.lifecycleStartAtMs - entry.receivedAtMs
+          : null,
+        firstStreamMs: entry.firstStreamAtMs
+          ? entry.firstStreamAtMs - entry.receivedAtMs
+          : null,
+      },
+      { sessionKey: entry.sessionKey, runId },
+    );
+  }
+
+  function complete(requestId, finalFrame, result = {}) {
+    const entry = entriesByRequestId.get(requestId);
+    if (!entry) return;
+    const completedAtMs = now();
+    entry.completedAtMs = completedAtMs;
+    entry.finalFrame = finalFrame;
+    options.emitDebug(
+      "operation_completed",
+      "info",
+      {
+        requestId,
+        operation: entry.operation,
+        class: entry.class,
+        elapsedMs: completedAtMs - entry.receivedAtMs,
+        resultSource: "typed_final_frame",
+        ...result,
+      },
+      { sessionKey: entry.sessionKey },
+    );
+  }
+
+  function fail(requestId, finalFrame, result = {}) {
+    const entry = entriesByRequestId.get(requestId);
+    if (!entry) return;
+    const failedAtMs = now();
+    entry.completedAtMs = failedAtMs;
+    entry.finalFrame = finalFrame;
+    options.emitDebug(
+      "operation_failed",
+      "warn",
+      {
+        requestId,
+        operation: entry.operation,
+        class: entry.class,
+        elapsedMs: failedAtMs - entry.receivedAtMs,
+        ...result,
+      },
+      { sessionKey: entry.sessionKey },
+    );
+  }
+
+  function queueDepthSnapshot() {
+    prune();
+    let transactional = 0;
+    for (const entry of entriesByRequestId.values()) {
+      if (!entry.completedAtMs && entry.class === "transactional") transactional += 1;
+    }
+    return {
+      transactional,
+      latestMutation: 0,
+      coalescableRead: 0,
+      bestEffort: 0,
+    };
+  }
+
+  function reconcileRequestIds(requestIds) {
+    prune();
+    const ids = Array.isArray(requestIds) ? requestIds : [];
+    return ids
+      .map((value) => (typeof value === "string" ? value.trim() : ""))
+      .filter(Boolean)
+      .map((requestId) => {
+        const entry = entriesByRequestId.get(requestId);
+        if (!entry) {
+          return {
+            requestId,
+            known: false,
+            receiptFrame: null,
+            finalFrame: null,
+          };
+        }
+        return {
+          requestId,
+          known: true,
+          receiptFrame: receiptFrame(entry),
+          finalFrame: entry.finalFrame || null,
+        };
+      });
+  }
+
+  return {
+    beginMessageSend,
+    markStarted,
+    markUpstreamAck,
+    markRunPhase,
+    queueDepthSnapshot,
+    reconcileRequestIds,
+  };
+}

package/dist/runtime/relay-service.js

@@ -33,10 +33,37 @@ function resolveOpenclawClient(openclawClientOverride, runtimeConfig, logger, st
   });
 }
 
+// Shared cross-context relay singleton. OpenClaw can load the plugin in
+// multiple isolated registration contexts (gateway startup, agent runs,
+// tool discovery) and each call to createOcuClawRelayService produces a
+// fresh service instance. Only one of those instances actually starts the
+// WebSocket-bearing relay; the others need to reach the same relay so that
+// tools registered in those contexts (e.g. render_glasses_ui) can call
+// sendGlassesUiRender / onGlassesUiResult against the real running relay.
+const SHARED_RELAY_SYMBOL = Symbol.for("ocuclaw.shared.relay");
+
+function getSharedRelay() {
+  return globalThis[SHARED_RELAY_SYMBOL] || null;
+}
+
+function setSharedRelay(relay) {
+  globalThis[SHARED_RELAY_SYMBOL] = relay;
+}
+
+function clearSharedRelay(relay) {
+  if (globalThis[SHARED_RELAY_SYMBOL] === relay) {
+    globalThis[SHARED_RELAY_SYMBOL] = null;
+  }
+}
+
 export function createOcuClawRelayService(opts = {}) {
   const baseLogger = normalizeLogger(opts.logger);
   let relay = null;
   let runtimeConfig = null;
+  const pendingGlassesUiResultHandlers = [];
+  const pendingGlassesUiNavEventHandlers = [];
+  const pendingDeviceInfoResponseHandlers = [];
+  const pendingAppClientDisconnectHandlers = [];
 
   function getRuntimeConfig() {
     if (!runtimeConfig) {
@@ -94,9 +121,38 @@ export function createOcuClawRelayService(opts = {}) {
       openclawClient,
       logger,
       consoleLogPath: opts.consoleLogPath,
+      activityStatusAdapter: {
+        freshnessWindowMs: config.freshnessWindowMs,
+        now: () => Date.now(),
+      },
     });
 
     relay = nextRelay;
+    setSharedRelay(nextRelay);
+    if (typeof nextRelay.onGlassesUiResult === "function" && pendingGlassesUiResultHandlers.length > 0) {
+      for (const handler of pendingGlassesUiResultHandlers) {
+        nextRelay.onGlassesUiResult(handler);
+      }
+    }
+    if (typeof nextRelay.onGlassesUiNavEvent === "function" && pendingGlassesUiNavEventHandlers.length > 0) {
+      for (const handler of pendingGlassesUiNavEventHandlers.splice(0)) {
+        nextRelay.onGlassesUiNavEvent(handler);
+      }
+    }
+    if (typeof nextRelay.onDeviceInfoResponse === "function" && pendingDeviceInfoResponseHandlers.length > 0) {
+      // splice(0) atomically drains the buffer so the unsubscribe returned to
+      // pre-start() callers becomes a safe no-op (it indexOf-s an empty list).
+      // After flush, handler lifetime is owned by the live relay's own
+      // unsubscribe; the pending buffer is no longer the source of truth.
+      for (const handler of pendingDeviceInfoResponseHandlers.splice(0)) {
+        nextRelay.onDeviceInfoResponse(handler);
+      }
+    }
+    if (typeof nextRelay.onAppClientDisconnect === "function" && pendingAppClientDisconnectHandlers.length > 0) {
+      for (const handler of pendingAppClientDisconnectHandlers.splice(0)) {
+        nextRelay.onAppClientDisconnect(handler);
+      }
+    }
     try {
       await Promise.resolve(nextRelay.start());
       logger.info(
@@ -104,6 +160,7 @@ export function createOcuClawRelayService(opts = {}) {
       );
       return nextRelay;
     } catch (err) {
+      clearSharedRelay(nextRelay);
       relay = null;
       throw err;
     }
@@ -117,14 +174,108 @@ export function createOcuClawRelayService(opts = {}) {
     const logger = normalizeLogger(stopOpts.logger || baseLogger);
     const activeRelay = relay;
     relay = null;
+    clearSharedRelay(activeRelay);
     await Promise.resolve(activeRelay.stop());
     logger.info("[ocuclaw] relay service stopped");
   }
 
+  function resolveLiveRelay() {
+    // Prefer the local-instance relay (started in this context); fall back to
+    // the cross-context shared relay (started in a sibling plugin-load context
+    // such as the gateway main process). This matters because OpenClaw can
+    // invoke a plugin's register() in multiple isolated contexts, but only
+    // one of them holds the running WebSocket relay.
+    return relay || getSharedRelay();
+  }
   return {
     getRuntimeConfig,
     getRelay() {
-      return relay;
+      return resolveLiveRelay();
+    },
+    sendGlassesUiRender(params) {
+      const liveRelay = resolveLiveRelay();
+      if (!liveRelay || typeof liveRelay.sendGlassesUiRender !== "function") {
+        throw new Error("ocuclaw relay not started");
+      }
+      liveRelay.sendGlassesUiRender(params);
+    },
+    sendGlassesUiSurfaceUpdate(params) {
+      const liveRelay = resolveLiveRelay();
+      if (!liveRelay || typeof liveRelay.sendGlassesUiSurfaceUpdate !== "function") {
+        throw new Error("ocuclaw relay not started");
+      }
+      liveRelay.sendGlassesUiSurfaceUpdate(params);
+    },
+    // Permanent glasses.lifecycle debug category passthrough (nav reconcile +
+    // cron pause/resume/tick). No-op until the relay is live; events are only
+    // recorded when the category is enabled via debug-set.
+    emitGlassesUiLifecycle(event, severity, data) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.emitGlassesUiLifecycle === "function") {
+        liveRelay.emitGlassesUiLifecycle(event, severity, data);
+      }
+    },
+    onGlassesUiResult(handler) {
+      if (typeof handler !== "function") {
+        return () => {};
+      }
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.onGlassesUiResult === "function") {
+        return liveRelay.onGlassesUiResult(handler);
+      }
+      // Relay not started yet — buffer until start() can register the handler.
+      pendingGlassesUiResultHandlers.push(handler);
+      return () => {
+        const idx = pendingGlassesUiResultHandlers.indexOf(handler);
+        if (idx !== -1) pendingGlassesUiResultHandlers.splice(idx, 1);
+      };
+    },
+    onGlassesUiNavEvent(handler) {
+      if (typeof handler !== "function") return () => {};
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.onGlassesUiNavEvent === "function") {
+        return liveRelay.onGlassesUiNavEvent(handler);
+      }
+      pendingGlassesUiNavEventHandlers.push(handler);
+      return () => {
+        const idx = pendingGlassesUiNavEventHandlers.indexOf(handler);
+        if (idx !== -1) pendingGlassesUiNavEventHandlers.splice(idx, 1);
+      };
+    },
+    onAppClientDisconnect(handler) {
+      if (typeof handler !== "function") return () => {};
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.onAppClientDisconnect === "function") {
+        return liveRelay.onAppClientDisconnect(handler);
+      }
+      // Relay not started yet — buffer until start() can register the handler.
+      pendingAppClientDisconnectHandlers.push(handler);
+      return () => {
+        const idx = pendingAppClientDisconnectHandlers.indexOf(handler);
+        if (idx !== -1) pendingAppClientDisconnectHandlers.splice(idx, 1);
+      };
+    },
+    sendDeviceInfoRequest(params) {
+      const liveRelay = resolveLiveRelay();
+      if (!liveRelay || typeof liveRelay.sendDeviceInfoRequest !== "function") {
+        throw new Error("ocuclaw relay not started");
+      }
+      liveRelay.sendDeviceInfoRequest(params);
+    },
+    onDeviceInfoResponse(handler) {
+      if (typeof handler !== "function") {
+        return () => {};
+      }
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.onDeviceInfoResponse === "function") {
+        return liveRelay.onDeviceInfoResponse(handler);
+      }
+      // Relay not started yet — buffer until start() can register the handler.
+      pendingDeviceInfoResponseHandlers.push(handler);
+      return () => {
+        const idx = pendingDeviceInfoResponseHandlers.indexOf(handler);
+        if (idx !== -1) pendingDeviceInfoResponseHandlers.splice(idx, 1);
+      };
     },
     getEvenAiSettingsSnapshot() {
       if (relay && typeof relay.getEvenAiSettingsSnapshot === "function") {
@@ -140,6 +291,55 @@ export function createOcuClawRelayService(opts = {}) {
         trackedThrowawayKeys: [],
       };
     },
+    getSessionTitle(sessionKey) {
+      if (relay && typeof relay.getSessionTitle === "function") {
+        return relay.getSessionTitle(sessionKey);
+      }
+      return null;
+    },
+    hasRecordedUserMessage(sessionKey) {
+      if (relay && typeof relay.hasRecordedUserMessage === "function") {
+        return relay.hasRecordedUserMessage(sessionKey);
+      }
+      // Fail-closed when the relay isn't running: block titling.
+      return false;
+    },
+    isNeuralSessionNamesEnabled(sessionKey) {
+      if (relay && typeof relay.isNeuralSessionNamesEnabled === "function") {
+        return relay.isNeuralSessionNamesEnabled(sessionKey);
+      }
+      return true;
+    },
+    isSessionUserLocked(sessionKey) {
+      if (relay && typeof relay.isSessionUserLocked === "function") {
+        return relay.isSessionUserLocked(sessionKey);
+      }
+      return false;
+    },
+    peekSessionKey() {
+      if (relay && typeof relay.peekSessionKey === "function") {
+        return relay.peekSessionKey();
+      }
+      return null;
+    },
+    recordNeuralSessionNamesEnabled(sessionKey, enabled) {
+      if (relay && typeof relay.recordNeuralSessionNamesEnabled === "function") {
+        relay.recordNeuralSessionNamesEnabled(sessionKey, enabled);
+      }
+    },
+    setSessionTitle(sessionKey, title, opts) {
+      if (relay && typeof relay.setSessionTitle === "function") {
+        return relay.setSessionTitle(sessionKey, title, opts);
+      }
+      return { ok: false, code: "relay_not_running" };
+    },
+    hasConnectedAppClient() {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.hasConnectedAppClient === "function") {
+        return liveRelay.hasConnectedAppClient();
+      }
+      return false;
+    },
     start,
     stop,
   };