ocuclaw 1.3.3 → 1.3.4

package/dist/runtime/relay-service.js

@@ -38,13 +38,6 @@ 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() {
@@ -110,9 +103,13 @@ export function createOcuClawRelayService(opts = {}) {
       token: config.relayToken,
       sessionLimit: config.sessionLimit,
       sonioxApiKey: config.sonioxApiKey,
-      debugPayloadMaxBytes: config.debugPayloadMaxBytes,
+      cartesiaApiKey: config.cartesiaApiKey,
       debugNoisyPolicies: config.debugNoisyPolicies,
       externalDebugToolsEnabled: config.externalDebugToolsEnabled,
+      allowDebugUpload: config.allowDebugUpload,
+      debugUploadMaxZipBytes: config.debugUploadMaxZipBytes,
+      debugUploadCapturePreset: config.debugUploadCapturePreset,
+      debugBundleSaveDir: config.debugBundleSaveDir,
       evenAiEnabled: config.evenAiEnabled,
       evenAiToken: config.evenAiToken,
       evenAiSystemPrompt: config.evenAiSystemPrompt,
@@ -145,10 +142,7 @@ export function createOcuClawRelayService(opts = {}) {
       }
     }
     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);
       }
@@ -192,11 +186,7 @@ export function createOcuClawRelayService(opts = {}) {
   }
 
   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 {
@@ -218,9 +208,7 @@ export function createOcuClawRelayService(opts = {}) {
       }
       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") {
@@ -235,7 +223,7 @@ export function createOcuClawRelayService(opts = {}) {
       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);
@@ -260,7 +248,7 @@ export function createOcuClawRelayService(opts = {}) {
       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);
@@ -282,7 +270,7 @@ export function createOcuClawRelayService(opts = {}) {
       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);
@@ -303,12 +291,7 @@ export function createOcuClawRelayService(opts = {}) {
         trackedThrowawayKeys: [],
       };
     },
-    // These reads back the session-title tool, the distiller gates, and the
-    // Channel-2 before_prompt_build hook — all of which can run in a sibling
-    // plugin-register context whose own `relay` is null. Resolve the live
-    // (possibly shared) relay so they reach the running instance, mirroring
-    // hasConnectedAppClient(); otherwise the distiller skips every run and the
-    // Channel-2 stop-notices never fire.
+
     getSessionTitle(sessionKey) {
       const liveRelay = resolveLiveRelay();
       if (liveRelay && typeof liveRelay.getSessionTitle === "function") {
@@ -321,7 +304,7 @@ export function createOcuClawRelayService(opts = {}) {
       if (liveRelay && typeof liveRelay.hasRecordedUserMessage === "function") {
         return liveRelay.hasRecordedUserMessage(sessionKey);
       }
-      // Fail-closed when no relay is running: block titling.
+
       return false;
     },
     isNeuralSessionNamesEnabled(sessionKey) {
@@ -352,9 +335,7 @@ export function createOcuClawRelayService(opts = {}) {
       }
       return { emoji: false, pace: false };
     },
-    // Distiller-sidecar passthroughs. Use the live relay (possibly a sibling
-    // register-context's shared relay) since the distiller may fire from a
-    // context whose own `relay` is null.
+
     getSessionTitleRecord(sessionKey) {
       const liveRelay = resolveLiveRelay();
       if (liveRelay && typeof liveRelay.getSessionTitleRecord === "function") {
@@ -419,9 +400,7 @@ export function createOcuClawRelayService(opts = {}) {
       return () => {};
     },
     peekSessionKey() {
-      // The set_session_title tool reads this before writing; like the adjacent
-      // session-title accessors it must reach the live (possibly shared) relay,
-      // or an explicit rename from a sibling tool context fails no_active_session.
+
       const liveRelay = resolveLiveRelay();
       if (liveRelay && typeof liveRelay.peekSessionKey === "function") {
         return liveRelay.peekSessionKey();
@@ -448,24 +427,18 @@ export function createOcuClawRelayService(opts = {}) {
       return false;
     },
     isGlassesSendBufferOverHighWater() {
-      // Roadmap 4a: glasses-ui paint-floor shed signal (glasses-ui-tool.ts
-      // already consults this; false = no shedding, the safe default).
+
       const liveRelay = resolveLiveRelay();
       if (liveRelay && typeof liveRelay.isGlassesSendBufferOverHighWater === "function") {
         return liveRelay.isGlassesSendBufferOverHighWater();
       }
       return false;
     },
-    // Tap-to-wake lane + busy signal (roadmap 6f). registerGlassesUiTool
-    // probes these at plugin register() time — BEFORE start() — and wires
-    // dispatchWake to null when the probe fails, so they must exist on the
-    // facade unconditionally and resolve the live (possibly shared) relay at
-    // call time, like every other passthrough above.
+
     dispatchGlassesWake(params) {
       const liveRelay = resolveLiveRelay();
       if (!liveRelay || typeof liveRelay.dispatchGlassesWake !== "function") {
-        // The wake controller retries once, then parks the wake in its
-        // durable outbox with a warn lifecycle — never silent after the ✓-ack.
+
         return Promise.reject(new Error("ocuclaw relay not started"));
       }
       return liveRelay.dispatchGlassesWake(params);
@@ -475,8 +448,7 @@ export function createOcuClawRelayService(opts = {}) {
       if (liveRelay && typeof liveRelay.isAgentTurnBusy === "function") {
         return liveRelay.isAgentTurnBusy(sessionKey);
       }
-      // Idle, not busy: a missing relay must surface through the dispatch
-      // path's failure handling, never suppress wakes as phantom-busy.
+
       return false;
     },
     start,

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

@@ -10,7 +10,7 @@ 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 }
+  const entries = new Map();
 
   function nowMs() {
     return normalizeNonNegativeInteger(now(), Date.now());

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

@@ -27,8 +27,7 @@ const transport = createRelayWorkerTransport({
   postToMain(message) {
     parentPort.postMessage(message);
   },
-  // Worker-thread console output never reaches the gateway's log file;
-  // forward log lines to the supervisor, which owns the real plugin logger.
+
   logger: {
     info(...args) { postWorkerLog("info", args); },
     warn(...args) { postWorkerLog("warn", args); },

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

@@ -167,8 +167,7 @@ export function createRelayWorkerHealthMonitor(options = {}) {
       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
@@ -179,14 +178,7 @@ export function createRelayWorkerHealthMonitor(options = {}) {
   }
 
   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";
     }

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

@@ -61,6 +61,8 @@ export const DEFAULT_WORKER_RPC_LIMITS = Object.freeze({
   httpRequestTimeoutMs: 60_000,
   httpMaxBodyBytes: 65_536,
   httpMaxResponseBytes: 262_144,
+
+  wsMaxMessageBytes: 25 * 1024 * 1024,
 });
 
 const ALLOWED_WORKER_STATUSES = new Set([
@@ -196,11 +198,14 @@ export function formatMainOperationReceived(data) {
   });
 }
 
-export function formatSendAck(requestId, status, error, errorCode) {
+export function formatSendAck(requestId, status, error, errorCode, data = {}) {
   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;
+  if (data && typeof data.runId === "string" && data.runId.trim()) {
+    msg.runId = data.runId.trim();
+  }
   return JSON.stringify(msg);
 }
 

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

@@ -109,6 +109,9 @@ export function createRelayWorkerSupervisor(options = {}) {
   let closing = false;
   let activeOperationBarrier = null;
   let mainHeartbeatTimer = null;
+  let restartTimer = null;
+  let restartAttempt = 0;
+  let workerReadyWatchdog = null;
   const clients = new Map();
   const pendingReadinessProbeRequests = new Map();
   const pendingAutomationStateRequests = new Map();
@@ -133,6 +136,8 @@ export function createRelayWorkerSupervisor(options = {}) {
       resolveReady = resolve;
       rejectReady = reject;
     });
+
+    readyPromise.catch(() => {});
     startPromise = readyPromise;
   }
 
@@ -181,6 +186,57 @@ export function createRelayWorkerSupervisor(options = {}) {
     if (typeof mainHeartbeatTimer.unref === "function") mainHeartbeatTimer.unref();
   }
 
+  function workerRestartBackoffBaseMs() {
+    return Number.isFinite(options.workerRestartBackoffBaseMs)
+      ? Math.max(0, Math.floor(options.workerRestartBackoffBaseMs))
+      : 250;
+  }
+
+  function workerRestartBackoffMaxMs() {
+    return Number.isFinite(options.workerRestartBackoffMaxMs)
+      ? Math.max(0, Math.floor(options.workerRestartBackoffMaxMs))
+      : 30000;
+  }
+
+  function workerReadyWatchdogMs() {
+
+    return Number.isFinite(options.workerReadyWatchdogMs) && options.workerReadyWatchdogMs > 0
+      ? Math.floor(options.workerReadyWatchdogMs)
+      : 10000;
+  }
+
+  function clearWorkerReadyWatchdog() {
+    if (workerReadyWatchdog) {
+      clearTimeout(workerReadyWatchdog);
+      workerReadyWatchdog = null;
+    }
+  }
+
+  function scheduleWorkerRestart() {
+    if (restartTimer || closing) return;
+    const base = Math.min(
+      workerRestartBackoffMaxMs(),
+      workerRestartBackoffBaseMs() * 2 ** Math.min(restartAttempt, 7),
+    );
+    const delay = base / 2 + Math.random() * (base / 2);
+    restartAttempt += 1;
+    if (typeof options.emitDebug === "function") {
+      options.emitDebug(
+        "relay.worker.health",
+        "worker_restart_backoff",
+        "warn",
+        null,
+        () => ({ attempt: restartAttempt, delayMs: Math.round(delay) }),
+      );
+    }
+    restartTimer = setTimeout(() => {
+      restartTimer = null;
+      if (closing) return;
+      startWorker();
+    }, delay);
+    if (typeof restartTimer.unref === "function") restartTimer.unref();
+  }
+
   function buildManifest() {
     workerEpoch += 1;
     return {
@@ -307,9 +363,7 @@ export function createRelayWorkerSupervisor(options = {}) {
 
   function postMainFrame(target, frame, clientId) {
     if (typeof frame !== "string") return;
-    // audit #19: parse the frame once. parseMessageType is itself a full JSON.parse,
-    // so deriving type from a single parseFrame avoids a second parse on the hot
-    // pages/status path below (and is neutral — still one parse — on other frames).
+
     const parsed = parseFrame(frame);
     const type = parsed && typeof parsed.type === "string" ? parsed.type : null;
     const message = {
@@ -329,16 +383,7 @@ export function createRelayWorkerSupervisor(options = {}) {
             : { statusRevision: revision };
       }
     }
-    // F17: requestId-scope the operation barrier. The barrier exists to
-    // preserve send-ordering in the worker path, but it used to divert EVERY
-    // broadcast/broadcastApp frame for the whole send→ack window — stalling
-    // unrelated live broadcasts (streaming deltas / activity / typing / status
-    // from a prior, still-streaming turn) until flush. Only hold a broadcast
-    // that is causally tied to the in-flight barrier.requestId; let everything
-    // else pass straight through. The send's own operation-received and ack are
-    // unicast (never diverted) and the op-received is posted synchronously
-    // ahead of the async ack, so "operation-received precedes that op's ack"
-    // holds independent of this barrier.
+
     if (
       activeOperationBarrier &&
       (target === "broadcast" || target === "broadcastApp") &&
@@ -506,6 +551,8 @@ export function createRelayWorkerSupervisor(options = {}) {
   function handleMessage(message) {
     if (!message || typeof message !== "object") return;
     if (message.kind === "worker.ready") {
+      restartAttempt = 0;
+      clearWorkerReadyWatchdog();
       addressValue = message.address || null;
       wssEvents.emit("listening");
       if (resolveReady) {
@@ -517,11 +564,14 @@ export function createRelayWorkerSupervisor(options = {}) {
     }
     if (message.kind === "worker.error") {
       logger.warn(`[relay-worker] ${message.message || "worker error"}`);
+
+      if (rejectReady && worker && typeof worker.terminate === "function") {
+        worker.terminate();
+      }
       return;
     }
     if (message.kind === "worker.log") {
-      // Worker-thread console output never reaches the gateway's structured
-      // log file, so the worker forwards its log lines here instead.
+
       const level =
         message.level === "warn" || message.level === "error" || message.level === "debug"
           ? message.level
@@ -649,11 +699,7 @@ export function createRelayWorkerSupervisor(options = {}) {
         disconnectedEntry.clientKind === "app" &&
         typeof options.onAppClientDisconnect === "function"
       ) {
-        // Drain a session's live-refresh crons only when THAT session's last
-        // app client disconnects (round-2: a same-session duplicate keeps it
-        // live; round-6: per-session so A drains independently of B). The
-        // disconnecting client is already removed from `clients`, so the
-        // excludeClientId is belt-and-suspenders.
+
         const drainSessionKey =
           typeof disconnectedEntry.sessionKey === "string" && disconnectedEntry.sessionKey
             ? disconnectedEntry.sessionKey
@@ -705,10 +751,7 @@ export function createRelayWorkerSupervisor(options = {}) {
       const pending = requestId ? pendingReadinessProbeRequests.get(requestId) : null;
       if (!pending || pending.targetClientId !== message.clientId) return;
       pendingReadinessProbeRequests.delete(requestId);
-      // Probe acks carry the app's CURRENT activeSessionKey — ground truth.
-      // Refresh the registry entry with it: the app's standalone snapshot
-      // republication can race a reconnecting socket and get lost, leaving the
-      // hello-frozen key here until the next app boot (quirk 8's second layer).
+
       if (ack && ack.ok !== false && typeof ack.activeSessionKey === "string" && ack.activeSessionKey) {
         const ackEntry = clients.get(message.clientId);
         if (ackEntry && ackEntry.readinessSnapshot) {
@@ -778,8 +821,7 @@ export function createRelayWorkerSupervisor(options = {}) {
       return;
     }
     if (message.kind === "worker.backpressure") {
-      // Roadmap 4a: heartbeat-cadence send-buffer pressure counts from the
-      // worker transport; relay-core latches them for the glasses paint shed.
+
       if (typeof options.onWorkerBackpressure === "function") {
         options.onWorkerBackpressure(message);
       }
@@ -810,20 +852,21 @@ export function createRelayWorkerSupervisor(options = {}) {
     nextWorker.on("message", handleMessage);
     nextWorker.on("error", (err) => {
       logger.error(`[relay-worker] worker error: ${err && err.message ? err.message : err}`);
-      if (rejectReady) rejectReady(err);
+
       wssEvents.emit("error", err);
     });
     const startedWorker = nextWorker;
     nextWorker.on("exit", (code) => {
-      const unexpected = !closing;
-      if (worker === startedWorker) worker = null;
+
+      const wasActive = worker === startedWorker;
+      if (!wasActive) return;
+      worker = null;
       stopMainHeartbeat();
-      if (unexpected) {
+      clearWorkerReadyWatchdog();
+      if (!closing) {
         const err = new Error(`relay worker exited with code ${code}`);
         logger.warn(`[relay-worker] ${err.message}`);
-        if (rejectReady) rejectReady(err);
-        resolveReady = null;
-        rejectReady = null;
+        const wasPreReady = Boolean(rejectReady);
         addressValue = null;
         clients.clear();
         pendingReadinessProbeRequests.clear();
@@ -831,18 +874,43 @@ export function createRelayWorkerSupervisor(options = {}) {
         if (wssEvents.listenerCount("error") > 0) {
           wssEvents.emit("error", err);
         }
-        resetReadyPromise();
-        startWorker();
+
+        if (!wasPreReady) {
+          resetReadyPromise();
+        }
+        scheduleWorkerRestart();
       }
     });
     const manifest = buildManifest();
     postToWorker(manifest);
     startMainHeartbeat(manifest.workerEpoch);
+
+    clearWorkerReadyWatchdog();
+    workerReadyWatchdog = setTimeout(() => {
+      workerReadyWatchdog = null;
+      if (closing || worker !== startedWorker) return;
+      logger.warn(
+        `[relay-worker] worker did not report ready within ${workerReadyWatchdogMs()}ms; terminating`,
+      );
+      if (typeof startedWorker.terminate === "function") startedWorker.terminate();
+    }, workerReadyWatchdogMs());
+    if (typeof workerReadyWatchdog.unref === "function") workerReadyWatchdog.unref();
     return nextWorker;
   }
 
   function close() {
     closing = true;
+
+    if (rejectReady) {
+      rejectReady(new Error("relay worker supervisor closed before ready"));
+      resolveReady = null;
+      rejectReady = null;
+    }
+    if (restartTimer) {
+      clearTimeout(restartTimer);
+      restartTimer = null;
+    }
+    clearWorkerReadyWatchdog();
     stopMainHeartbeat();
     if (!worker) {
       startPromise = null;
@@ -944,12 +1012,6 @@ export function createRelayWorkerSupervisor(options = {}) {
     });
   }
 
-  // The WebUI's reconnect hello embeds its readiness snapshot WITHOUT
-  // emittedAtMs (toProtocolHelloReadinessSnapshotJson omits it), but the
-  // automation-state gate requires a finite emittedAtMs to count the client
-  // as published. Stamp ingest time so a reconnect hello counts as a
-  // publication — otherwise every relay restart leaves `inspect state`
-  // returning snapshot_unavailable until the sim/app client is cycled.
   function normalizeIngestedReadinessSnapshot(snapshot) {
     if (!snapshot || typeof snapshot !== "object") {
       return null;