ocuclaw 0.1.0 → 1.2.4

package/README.md

@@ -1,9 +1,11 @@
 # OcuClaw
 
-OcuClaw is an OpenClaw plugin for Even G2 smart glasses.
+OcuClaw is an OpenClaw plugin for Even G2 smart glasses. Use the OcuClaw application within Even Hub App Store to connect the client side.
 
 ## Install
 
+Install the plugin from the OpenClaw CLI:
+
 ```bash
 openclaw plugins install ocuclaw
 openclaw plugins enable ocuclaw
@@ -11,15 +13,55 @@ openclaw plugins enable ocuclaw
 
 ## Configure
 
-Set the relay token before starting or restarting the OpenClaw gateway:
+Required:
+
+Set the OcuClaw relay token. This is a user-created password that must match the relay server token field in the OcuClaw application within Even Hub App Store.
 
 ```bash
 openclaw config set plugins.entries.ocuclaw.config.relayToken "<relay-token>"
 ```
 
-Optional settings live under `plugins.entries.ocuclaw.config.*`.
+Recommended:
+
+- `sonioxApiKey`: Enables Soniox speech-to-text for voice input.
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.sonioxApiKey "<soniox-api-key>"
+```
+
+- `evenAiEnabled`: Enables Even AI integration for OcuClaw.
 
-## Notes
+```bash
+openclaw config set plugins.entries.ocuclaw.config.evenAiEnabled true --strict-json
+```
+
+- `evenAiToken`: Sets the user-created password for Even AI requests. This must match the password set in the Even AI Agent Configure section within the Even Realities app.
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.evenAiToken "<even-ai-token>"
+```
 
-- Plugin id: `ocuclaw`
-- The WebUI is a separate artifact and is not bundled into this npm package.
+Advanced optional settings:
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.wsBind "127.0.0.1"
+openclaw config set plugins.entries.ocuclaw.config.wsPort 9000 --strict-json
+openclaw config set plugins.entries.ocuclaw.config.sessionLimit 10 --strict-json
+openclaw config set plugins.entries.ocuclaw.config.externalDebugToolsEnabled true --strict-json
+```
+
+## Restart
+
+Restart the gateway so the plugin and config changes take effect:
+
+```bash
+openclaw gateway restart
+```
+
+## Verify
+
+```bash
+openclaw plugins inspect ocuclaw
+openclaw plugins doctor
+openclaw gateway status
+```

package/dist/domain/debug-store.js

@@ -458,11 +458,12 @@ function redactStringValue(value, mode, keyName) {
     }
   }
 
-  function emit(event) {
+  function emit(event, options) {
     const raw = event || {};
     const cat = typeof raw.cat === "string" ? raw.cat.trim() : "";
+    const force = !!(options && options.force === true);
     if (!cat) return false;
-    if (!isEnabled(cat)) return false;
+    if (!force && !isEnabled(cat)) return false;
 
     const ts = Number.isFinite(raw.ts) ? Math.floor(raw.ts) : nowFn();
     const eventName =

package/dist/runtime/downstream-handler.js

@@ -63,6 +63,8 @@ function normalizeLogger(logger) {
  *   Returns true if the OpenClaw gateway connection is active.
  * @param {(clientId: string, payload: object) => void} [opts.onEventDebug]
  *   Optional structured client debug-event callback.
+ * @param {(clientId: string, payload: object) => Promise<object>|object} [opts.onReadinessProbe]
+ *   Optional dedicated readiness-probe dispatcher.
  * @returns {object} Handler instance
  */
 function createDownstreamHandler(opts) {
@@ -95,6 +97,7 @@ function createDownstreamHandler(opts) {
   const onDebugDump = opts.onDebugDump || null;
   const onEventDebug = opts.onEventDebug || null;
   const onRemoteControl = opts.onRemoteControl || null;
+  const onReadinessProbe = opts.onReadinessProbe || null;
   const getSnapshotRevision = opts.getSnapshotRevision || null;
 
   /** Client IDs subscribed to raw protocol frame forwarding. */
@@ -139,6 +142,8 @@ function createDownstreamHandler(opts) {
     pages: "ocuclaw.view.pages.snapshot",
     protocolSubscribe: "ocuclaw.protocol.tap.subscribe",
     protocolFrame: "ocuclaw.protocol.tap.frame",
+    readinessProbeAck: "ocuclaw.readiness.probe.ack",
+    readinessProbeRequest: "ocuclaw.readiness.probe.request",
     remoteControl: "ocuclaw.remote.control",
     requestSonioxTemporaryKey: "requestSonioxTemporaryKey",
     sonioxModelsGet: "ocuclaw.voice.soniox.models.get",
@@ -234,7 +239,8 @@ function createDownstreamHandler(opts) {
     return (
       messageType === "debug-set" ||
       messageType === "debug-dump" ||
-      messageType === "remote-control"
+      messageType === "remote-control" ||
+      messageType === APP_PROTOCOL.readinessProbeRequest
     );
   }
 
@@ -827,6 +833,63 @@ function createDownstreamHandler(opts) {
     });
   }
 
+  function formatReadinessProbeRequest(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.readinessProbeRequest,
+      requestId:
+        data && typeof data.requestId === "string" && data.requestId
+          ? data.requestId
+          : null,
+      sinceMs:
+        data && Number.isFinite(Number(data.sinceMs))
+          ? Math.max(0, Math.floor(Number(data.sinceMs)))
+          : 0,
+      sessionKey:
+        data && typeof data.sessionKey === "string" && data.sessionKey
+          ? data.sessionKey
+          : null,
+    });
+  }
+
+  function formatReadinessProbeAck(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.readinessProbeAck,
+      ok: data && data.ok !== false,
+      requestId:
+        data && typeof data.requestId === "string" && data.requestId
+          ? data.requestId
+          : null,
+      reasonCode:
+        data && typeof data.reasonCode === "string" && data.reasonCode
+          ? data.reasonCode
+          : null,
+      message:
+        data && typeof data.message === "string" && data.message
+          ? data.message
+          : null,
+      activeSessionKey:
+        data && typeof data.activeSessionKey === "string" && data.activeSessionKey
+          ? data.activeSessionKey
+          : null,
+      emittedAtMs:
+        data && Number.isFinite(Number(data.emittedAtMs))
+          ? Math.max(0, Math.floor(Number(data.emittedAtMs)))
+          : null,
+      clientId:
+        data && typeof data.clientId === "string" && data.clientId
+          ? data.clientId
+          : null,
+      clientName:
+        data && typeof data.clientName === "string" && data.clientName
+          ? data.clientName
+          : null,
+      clientVersion:
+        data && typeof data.clientVersion === "string" && data.clientVersion
+          ? data.clientVersion
+          : null,
+    });
+  }
+
   function normalizeCategories(raw, fieldName) {
     if (raw === undefined || raw === null) return [];
     if (!Array.isArray(raw)) {
@@ -1124,6 +1187,26 @@ function createDownstreamHandler(opts) {
     ) {
       return "debug-close-app-client";
     }
+    if (
+      normalized === "debug-screen-off-worker-on" ||
+      normalized === "debug_screen_off_worker_on" ||
+      normalized === "debugscreenoffworkeron" ||
+      normalized === "screen-off-worker-on" ||
+      normalized === "screen_off_worker_on" ||
+      normalized === "screenoffworkeron"
+    ) {
+      return "debug-screen-off-worker-on";
+    }
+    if (
+      normalized === "debug-screen-off-worker-off" ||
+      normalized === "debug_screen_off_worker_off" ||
+      normalized === "debugscreenoffworkeroff" ||
+      normalized === "screen-off-worker-off" ||
+      normalized === "screen_off_worker_off" ||
+      normalized === "screenoffworkeroff"
+    ) {
+      return "debug-screen-off-worker-off";
+    }
     throw new Error(`unsupported remote relayAction: ${raw}`);
   }
 
@@ -1187,12 +1270,19 @@ function createDownstreamHandler(opts) {
 
     const payload = {};
 
-    const modelRef = parseOptionalTrimmedString(msg.modelRef);
-    if (modelRef) {
-      if (!modelRef.includes("/")) {
-        throw new Error("modelRef must be in provider/id format");
+    if (Object.prototype.hasOwnProperty.call(msg, "modelRef")) {
+      if (typeof msg.modelRef !== "string") {
+        throw new Error("modelRef must be in provider/id format or blank");
+      }
+      const modelRef = msg.modelRef.trim();
+      if (!modelRef) {
+        payload.modelRef = "";
+      } else {
+        if (!modelRef.includes("/")) {
+          throw new Error("modelRef must be in provider/id format");
+        }
+        payload.modelRef = modelRef;
       }
-      payload.modelRef = modelRef;
     }
 
     if (Object.prototype.hasOwnProperty.call(msg, "thinkingLevel")) {
@@ -1489,6 +1579,25 @@ function createDownstreamHandler(opts) {
     throw new Error(`unsupported remote-control action: ${actionRaw}`);
   }
 
+  function parseReadinessProbe(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("readiness probe payload must be an object");
+    }
+    const requestId = parseOptionalTrimmedString(msg.requestId);
+    if (!requestId) {
+      throw new Error("readiness probe requires requestId");
+    }
+    const sinceMs = parseOptionalNonNegativeNumber(msg.sinceMs, "sinceMs");
+    if (sinceMs === undefined) {
+      throw new Error("readiness probe sinceMs must be a non-negative number");
+    }
+    return {
+      requestId,
+      sinceMs,
+      sessionKey: parseOptionalTrimmedString(msg.sessionKey) || null,
+    };
+  }
+
   const ATTACHMENT_MAX_DECODED_BYTES = 5_000_000;
   const ATTACHMENT_MAX_ENCODED_CHARS =
     Math.ceil((ATTACHMENT_MAX_DECODED_BYTES * 4) / 3) + 16;
@@ -2591,6 +2700,63 @@ function createDownstreamHandler(opts) {
     }
   }
 
+  function handleReadinessProbe(clientId, msg) {
+    if (!onReadinessProbe) {
+      return { unicast: formatError("readiness probe is not available") };
+    }
+
+    let payload;
+    try {
+      payload = parseReadinessProbe(msg);
+    } catch (err) {
+      return { unicast: formatError(err.message) };
+    }
+
+    const finalize = (result) => {
+      const resolved = result || {};
+      const requestId = resolved.requestId || payload.requestId;
+      if (
+        resolved.ok === false ||
+        !resolved.targetClientId ||
+        !resolved.probe
+      ) {
+        return {
+          unicast: formatReadinessProbeAck({
+            ok: false,
+            requestId,
+            reasonCode: resolved.reasonCode || null,
+            message: resolved.message || "readiness probe was not dispatched",
+            activeSessionKey: resolved.activeSessionKey || null,
+            emittedAtMs: resolved.emittedAtMs || null,
+          }),
+        };
+      }
+
+      return {
+        readinessProbe: {
+          requestId,
+          targetClientId: resolved.targetClientId,
+          message: formatReadinessProbeRequest(resolved.probe),
+        },
+      };
+    };
+
+    try {
+      const result = onReadinessProbe(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => finalize(resolved),
+          (err) => ({
+            unicast: formatError(err.message || "readiness probe failed"),
+          }),
+        );
+      }
+      return finalize(result);
+    } catch (err) {
+      return { unicast: formatError(err.message || "readiness probe failed") };
+    }
+  }
+
   // --- Public API ---
 
   return {
@@ -2681,6 +2847,8 @@ function createDownstreamHandler(opts) {
           return handleDebugDump(clientId, msg);
         case "remote-control":
           return handleRemoteControl(clientId, msg);
+        case APP_PROTOCOL.readinessProbeRequest:
+          return handleReadinessProbe(clientId, msg);
         case APP_PROTOCOL.debugEvent:
           return handleEventDebug(clientId, msg);
         default:
@@ -2721,6 +2889,8 @@ function createDownstreamHandler(opts) {
     formatDebugConfigSnapshot,
     formatRemoteControl,
     formatRemoteControlAck,
+    formatReadinessProbeRequest,
+    formatReadinessProbeAck,
     formatError,
 
     /**

package/dist/runtime/downstream-server.js

@@ -97,6 +97,10 @@ function createDownstreamServer(opts) {
   const syncState = new Map();
   /** @type {Map<string, {visibilityState: "hidden"|"visible"|"blurred"|null, streamChars: number|null, lastHeartbeatAtMs: number|null, lastRelayStreamingActivityAtMs: number|null, interactionStage: "idle"|"listening"|"voice_handoff"|"thinking"|"streaming"|"post_turn_drain", cadenceBucket: "idle"|"active_non_stream"|"active_stream", nudgeActive: boolean, nudgeIntervalMs: number|null, nudgeStartedAtMs: number|null, lastNudgeAtMs: number|null, stalledHeartbeatCount: number, nudgeTimer: any, idleDeactivateTimer: any, staleHeartbeatTimer: any, hardTimeoutTimer: any}>} */
   const clientNudgeState = new Map();
+  /** @type {Map<string, {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, 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, string>} */
   const unresolvedApprovals = new Map();
   let nextClientId = 1;
@@ -105,6 +109,9 @@ function createDownstreamServer(opts) {
     approvalResolved: "ocuclaw.approval.resolved",
     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",
     status: "ocuclaw.runtime.status",
@@ -174,6 +181,20 @@ function createDownstreamServer(opts) {
     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();
@@ -262,6 +283,90 @@ function createDownstreamServer(opts) {
         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 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 emittedAtMs = parseOptionalNonNegativeInt(value.emittedAtMs);
+    if (
+      clientDebugEnabled === null &&
+      runtimeDiagnosticsVisible === null &&
+      perfNoisyDebugMuted === null &&
+      perfPayloadLiteMode === null &&
+      !activeSessionKey &&
+      !bundleIdentity &&
+      emittedAtMs === null
+    ) {
+      return null;
+    }
+    return {
+      clientDebugEnabled,
+      runtimeDiagnosticsVisible,
+      perfNoisyDebugMuted,
+      perfPayloadLiteMode,
+      activeSessionKey: activeSessionKey || null,
+      bundleIdentity,
+      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),
     };
   }
 
@@ -449,6 +554,81 @@ function createDownstreamServer(opts) {
     };
   }
 
+  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 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),
+      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 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 clearClientNudgeTimer(state, key, clearFn = clearTimeout) {
     if (!state || !state[key]) return;
     clearFn(state[key]);
@@ -888,6 +1068,50 @@ function createDownstreamServer(opts) {
     ws.send(message);
   }
 
+  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 getServerResumeState() {
     if (!getCurrentResumeState) {
       return { pagesRevision: null, statusRevision: null };
@@ -1191,6 +1415,9 @@ function createDownstreamServer(opts) {
           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"}`,
         );
@@ -1244,6 +1471,21 @@ function createDownstreamServer(opts) {
         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;
+      }
+
       if (parsed && parsed.type === APP_PROTOCOL.resume) {
         const sync = syncState.get(clientId);
         if (sync) sync.resumeReceived = true;
@@ -1307,6 +1549,8 @@ function createDownstreamServer(opts) {
       const protocol = protocolState.get(clientId);
       syncState.delete(clientId);
       protocolState.delete(clientId);
+      clientReadinessSnapshotState.delete(clientId);
+      clearPendingReadinessProbesForClient(clientId);
       clearClientNudgeTimers(clientId);
       clientNudgeState.delete(clientId);
       handler.removeClient(clientId);
@@ -1379,6 +1623,54 @@ function createDownstreamServer(opts) {
       }
     }
 
+    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.broadcast) {
       if (Array.isArray(result.broadcast)) {
         for (const msg of result.broadcast) broadcast(msg);
@@ -1519,6 +1811,37 @@ function createDownstreamServer(opts) {
     return countConnectedAppClients(excludeClientId);
   }
 
+  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.
    *
@@ -1534,6 +1857,8 @@ function createDownstreamServer(opts) {
         clearClientNudgeTimers(clientId);
       }
       clientNudgeState.clear();
+      clientReadinessSnapshotState.clear();
+      pendingReadinessProbeRequests.clear();
       for (const [, ws] of clients) {
         ws.close();
       }
@@ -1547,6 +1872,7 @@ function createDownstreamServer(opts) {
     unicast,
     getClientIds,
     getConnectedAppCount,
+    getReadinessSnapshot,
     closeConnectedAppClients,
     getClientNudgeState(clientId) {
       return cloneClientNudgeState(clientNudgeState.get(clientId) || null);

package/dist/runtime/relay-core.js

@@ -371,8 +371,9 @@ function createRelay(opts) {
    * @param {object} context
    * @param {() => object} buildData
    */
-  function emitDebug(cat, event, severity, context, buildData) {
-    if (!debugStore.isEnabled(cat)) return;
+  function emitDebug(cat, event, severity, context, buildData, options) {
+    const force = !!(options && options.force === true);
+    if (!force && !debugStore.isEnabled(cat)) return;
 
     let data = {};
     if (typeof buildData === "function") {
@@ -394,7 +395,15 @@ function createRelay(opts) {
     if (context && context.runId) payload.runId = context.runId;
     if (context && context.screen) payload.screen = context.screen;
 
-    debugStore.emit(payload);
+    debugStore.emit(payload, { force });
+  }
+
+  function isForcedReadinessProofEvent(payload) {
+    return !!(
+      payload &&
+      payload.cat === "app.lifecycle" &&
+      payload.event === "readiness_probe_received"
+    );
   }
 
   function scheduleSimulateStreamTimer(delayMs, callback) {
@@ -879,6 +888,20 @@ function createRelay(opts) {
     getAgentName() {
       return upstreamRuntime ? upstreamRuntime.getAgentName() : null;
     },
+    isPinnedFirstUserMessageKey(sessionKey) {
+      const normalizedSessionKey = normalizeEvenAiSessionKeyForLookup(sessionKey);
+      if (!normalizedSessionKey) {
+        return false;
+      }
+      const trackedThrowawayKeys =
+        typeof evenAiSettingsStore.getTrackedThrowawayKeys === "function"
+          ? evenAiSettingsStore.getTrackedThrowawayKeys()
+          : [];
+      return dedupeNormalizedSessionKeys(trackedThrowawayKeys).some(
+        (trackedKey) =>
+          trackedKey.toLowerCase() === normalizedSessionKey.toLowerCase(),
+      );
+    },
     onSessionStateReset: resetActivityStatusAdapter,
     onPagesChanged: cachePages,
     onStatusChanged: broadcastStatus,
@@ -1324,7 +1347,7 @@ function createRelay(opts) {
     },
 
     onGetStatus() {
-      return buildStatusObject();
+      return buildStatusObject({ includeDownstreamReadiness: true });
     },
 
     onGetSessionModelConfig() {
@@ -1459,7 +1482,8 @@ function createRelay(opts) {
     onEventDebug(clientId, payload) {
       if (!payload || typeof payload !== "object") return;
       const cat = payload.cat;
-      if (!debugStore.isEnabled(cat)) return;
+      const forceStore = isForcedReadinessProofEvent(payload);
+      if (!forceStore && !debugStore.isEnabled(cat)) return;
       emitDebug(
         cat,
         payload.event,
@@ -1473,6 +1497,7 @@ function createRelay(opts) {
           clientId,
           ...(payload.data || {}),
         }),
+        { force: forceStore },
       );
     },
 
@@ -1637,6 +1662,110 @@ function createRelay(opts) {
         control,
       };
     },
+
+    onReadinessProbe(clientId, request) {
+      const now = Date.now();
+      const requestId =
+        (typeof request.requestId === "string" && request.requestId.trim()) ||
+        `readiness-${now}-${Math.random().toString(16).slice(2, 8)}`;
+      const sinceMs = Number.isFinite(Number(request && request.sinceMs))
+        ? Math.max(0, Math.floor(Number(request.sinceMs)))
+        : now;
+      const snapshot =
+        server && typeof server.getReadinessSnapshot === "function"
+          ? server.getReadinessSnapshot()
+          : {
+              connectedClientCount: 0,
+              fanoutRecipientCount: 0,
+              clients: [],
+            };
+      const targetClientId =
+        snapshot &&
+        snapshot.connectedClientCount === 1 &&
+        snapshot.fanoutRecipientCount === 1 &&
+        Array.isArray(snapshot.clients) &&
+        snapshot.clients.length === 1 &&
+        typeof snapshot.clients[0].clientId === "string"
+          ? snapshot.clients[0].clientId
+          : null;
+
+      emitDebug(
+        "relay.protocol",
+        "readiness_probe_requested",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          sinceMs,
+          requestedSessionKey:
+            typeof request.sessionKey === "string" && request.sessionKey.trim()
+              ? request.sessionKey.trim()
+              : null,
+          connectedClientCount:
+            snapshot && Number.isFinite(snapshot.connectedClientCount)
+              ? snapshot.connectedClientCount
+              : 0,
+          fanoutRecipientCount:
+            snapshot && Number.isFinite(snapshot.fanoutRecipientCount)
+              ? snapshot.fanoutRecipientCount
+              : 0,
+        }),
+      );
+
+      if (
+        !snapshot ||
+        snapshot.connectedClientCount <= 0 ||
+        snapshot.fanoutRecipientCount <= 0
+      ) {
+        return {
+          ok: false,
+          requestId,
+          reasonCode: "no_downstream_client",
+          message: "No downstream app clients connected",
+        };
+      }
+
+      if (
+        snapshot.connectedClientCount > 1 ||
+        snapshot.fanoutRecipientCount > 1 ||
+        !targetClientId
+      ) {
+        return {
+          ok: false,
+          requestId,
+          reasonCode: "multi_recipient_fanout",
+          message: "Multiple downstream app clients connected",
+        };
+      }
+
+      emitDebug(
+        "relay.protocol",
+        "readiness_probe_dispatched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          targetClientId,
+          sinceMs,
+        }),
+      );
+
+      return {
+        ok: true,
+        requestId,
+        targetClientId,
+        probe: {
+          requestId,
+          sinceMs,
+          sessionKey:
+            typeof request.sessionKey === "string" && request.sessionKey.trim()
+              ? request.sessionKey.trim()
+              : null,
+        },
+      };
+    },
   });
 
   // --- Downstream server ---
@@ -1739,8 +1868,9 @@ function createRelay(opts) {
 
   // --- Helpers ---
 
-  function buildStatusObject() {
-    return {
+  function buildStatusObject(options = {}) {
+    const includeDownstreamReadiness = options.includeDownstreamReadiness === true;
+    const status = {
       openclaw:
         upstreamRuntime && upstreamRuntime.isConnected()
           ? "connected"
@@ -1749,6 +1879,18 @@ function createRelay(opts) {
       session: sessionService.ensureSessionKey(),
       evenAiEnabled: opts.evenAiEnabled === true,
     };
+    if (includeDownstreamReadiness) {
+      status.downstreamReadiness =
+        server && typeof server.getReadinessSnapshot === "function"
+          ? server.getReadinessSnapshot()
+          : {
+              connectedClientCount: 0,
+              fanoutRecipientCount: 0,
+              updatedAtMs: null,
+              clients: [],
+            };
+    }
+    return status;
   }
 
   function cachePages(pages) {

package/dist/runtime/session-service.js

@@ -53,6 +53,10 @@ export function createSessionService(opts = {}) {
     typeof opts.onSessionModelConfig === "function"
       ? opts.onSessionModelConfig
       : null;
+  const isPinnedFirstUserMessageKey =
+    typeof opts.isPinnedFirstUserMessageKey === "function"
+      ? opts.isPinnedFirstUserMessageKey
+      : null;
 
   /** Current session key. Generated on first use. */
   let currentSessionKey = null;
@@ -390,7 +394,7 @@ export function createSessionService(opts = {}) {
     }
     const request = { key: canonicalKey };
     if (patch && typeof patch.modelRef === "string") {
-      request.model = patch.modelRef;
+      request.model = patch.modelRef.trim() ? patch.modelRef : null;
     }
     if (patch && Object.prototype.hasOwnProperty.call(patch, "thinkingLevel")) {
       request.thinkingLevel =
@@ -717,11 +721,7 @@ export function createSessionService(opts = {}) {
         if (!sessionKey || !normalized) continue;
         out.set(sessionKey, normalized);
       }
-      while (out.size > firstUserMessageCacheLimit) {
-        const oldestKey = out.keys().next().value;
-        if (oldestKey === undefined) break;
-        out.delete(oldestKey);
-      }
+      pruneFirstUserMessageEntries(out);
       return out;
     } catch {
       return new Map();
@@ -756,11 +756,7 @@ export function createSessionService(opts = {}) {
   }
 
   function pruneFirstSentUserMessageCache() {
-    while (firstSentUserMessageBySession.size > firstUserMessageCacheLimit) {
-      const oldestKey = firstSentUserMessageBySession.keys().next().value;
-      if (oldestKey === undefined) break;
-      firstSentUserMessageBySession.delete(oldestKey);
-    }
+    pruneFirstUserMessageEntries(firstSentUserMessageBySession);
   }
 
   function recordFirstSentUserMessage(sessionKey, text) {
@@ -810,10 +806,41 @@ export function createSessionService(opts = {}) {
   }
 
   function pruneFirstUserMessageCache() {
-    while (firstUserMessageCache.size > firstUserMessageCacheLimit) {
-      const oldestKey = firstUserMessageCache.keys().next().value;
-      if (oldestKey === undefined) break;
-      firstUserMessageCache.delete(oldestKey);
+    pruneFirstUserMessageEntries(firstUserMessageCache);
+  }
+
+  function shouldPinFirstUserMessageKey(sessionKey) {
+    if (!isPinnedFirstUserMessageKey || typeof sessionKey !== "string") {
+      return false;
+    }
+    const normalizedKey = sessionKey.trim();
+    if (!normalizedKey) {
+      return false;
+    }
+    try {
+      return isPinnedFirstUserMessageKey(normalizedKey) === true;
+    } catch (err) {
+      logger.warn(
+        `[relay] first-user cache pin callback failed for ${normalizedKey}: ${err && err.message ? err.message : err}`,
+      );
+      return false;
+    }
+  }
+
+  function pruneFirstUserMessageEntries(cache) {
+    while (cache.size > firstUserMessageCacheLimit) {
+      let evicted = false;
+      for (const sessionKey of cache.keys()) {
+        if (shouldPinFirstUserMessageKey(sessionKey)) {
+          continue;
+        }
+        cache.delete(sessionKey);
+        evicted = true;
+        break;
+      }
+      if (!evicted) {
+        break;
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocuclaw",
-  "version": "0.1.0",
+  "version": "1.2.4",
   "description": "OcuClaw for Even G2 smart glasses, powered by OpenClaw.",
   "type": "module",
   "main": "./dist/index.js",