ocuclaw 0.1.0 → 1.3.0

package/dist/runtime/relay-core.js

@@ -1,9 +1,15 @@
 import * as fs from "node:fs";
-import * as http from "node:http";
 import * as path from "node:path";
+import * as childProcess from "node:child_process";
+import { EventEmitter } from "node:events";
+import { createPluginUpdateService } from "./plugin-update-service.js";
 import * as conversationStateModule from "../domain/conversation-state.js";
 import { createDebugStore } from "../domain/debug-store.js";
+import { summarizeGlassesUiContent } from "../domain/glasses-ui-content-summary.js";
 import { composeReadabilitySystemPrompt } from "../domain/readability-system-prompt.js";
+import { composeNeuralEmojiReactorSystemPrompt } from "../domain/neural-emoji-reactor-system-prompt.js";
+import { composeNeuralPaceModulatorSystemPrompt } from "../domain/neural-pace-modulator-system-prompt.js";
+import { composeGlassesUiNudgeSystemPrompt } from "../domain/glasses-ui-system-prompt.js";
 import { createActivityStatusAdapter } from "../domain/activity-status-adapter.js";
 import { createEvenAiEndpoint } from "../even-ai/even-ai-endpoint.js";
 import { createEvenAiRouter } from "../even-ai/even-ai-router.js";
@@ -12,15 +18,20 @@ import { createEvenAiSettingsStore } from "../even-ai/even-ai-settings-store.js"
 import { createPluginOpenclawClient } from "../gateway/openclaw-client.js";
 import { createPluginRpcGatewayBridge } from "../gateway/gateway-bridge.js";
 import { createDownstreamHandler } from "./downstream-handler.js";
-import { createDownstreamServer } from "./downstream-server.js";
 import { createOcuClawSettingsStore } from "./ocuclaw-settings-store.js";
+import { createRelayHealthMonitor } from "./relay-health-monitor.js";
+import { createRelayOperationRegistry } from "./relay-operation-registry.js";
+import { createRelayWorkerSupervisor } from "./relay-worker-supervisor.js";
 import { createSessionService } from "./session-service.js";
 import { createUpstreamRuntime } from "./upstream-runtime.js";
 
 const SONIOX_TEMP_KEY_URL = "https://api.soniox.com/v1/auth/temporary-api-key";
 const SONIOX_MODELS_URL = "https://api.soniox.com/v1/models";
 const DEFAULT_SONIOX_TEMP_KEY_EXPIRES_IN_SECONDS = 3600;
-const EVEN_AI_HANDLED = Symbol.for("ocuclaw.evenai.handled");
+// Maximum time (ms) to wait for a Soniox temp-key mint before aborting the
+// fetch.  8 s is a conservative cold-path ceiling; tests inject a tiny value
+// via opts.sonioxTemporaryKeyMintTimeoutMs to make assertions fast.
+const DEFAULT_SONIOX_TEMP_KEY_MINT_TIMEOUT_MS = 8000;
 const EVEN_AI_NAMESPACE_PREFIX = "ocuclaw:even-ai";
 const EVEN_AI_NAMESPACE_PREFIX_WITH_DELIMITER = "ocuclaw:even-ai:";
 const LISTEN_INTERCEPT_RECOVERY_ERROR = "Voice interrupted; retry";
@@ -159,6 +170,10 @@ function normalizeSonioxTemporaryKeyErrorCode(err) {
       : "";
   const lowered = message.toLowerCase();
   if (!message) return "soniox_temp_key_request_failed";
+  // AbortError from the per-fetch timeout AbortController.
+  if (err && err.name === "AbortError") {
+    return "soniox_temp_key_mint_timeout";
+  }
   if (lowered.includes("api key is not configured")) {
     return "soniox_temp_key_not_configured";
   }
@@ -210,31 +225,71 @@ function normalizeSonioxModelEntryRows(result) {
   return models;
 }
 
-function createOwnedRelayHttpServer() {
-  return http.createServer((_req, res) => {
-    if (res.writableEnded || res[EVEN_AI_HANDLED]) {
-      return;
+function createBufferedHttpRequest(envelope) {
+  const req = new EventEmitter();
+  req.method = envelope && envelope.method ? envelope.method : "GET";
+  req.url = envelope && envelope.url ? envelope.url : "/";
+  req.headers = envelope && envelope.headers && typeof envelope.headers === "object"
+    ? envelope.headers
+    : {};
+  req.socket = {
+    remoteAddress: "127.0.0.1",
+  };
+  const body = Buffer.from((envelope && envelope.bodyBase64) || "", "base64");
+  process.nextTick(() => {
+    if (body.length > 0) {
+      req.emit("data", body);
     }
-    res.statusCode = 404;
-    res.setHeader("content-type", "text/plain; charset=utf-8");
-    res.end("not found");
+    req.emit("end");
   });
+  return req;
 }
 
-function listenOwnedRelayHttpServer(httpServer, host, port) {
-  if (!httpServer || httpServer.listening) {
-    return;
-  }
-  httpServer.listen(port, host);
-}
-
-function closeOwnedRelayHttpServer(httpServer) {
-  if (!httpServer || !httpServer.listening) {
-    return Promise.resolve();
-  }
-  return new Promise((resolve) => {
-    httpServer.close(() => resolve());
-  });
+function createBufferedHttpResponse(maxResponseBytes) {
+  const headers = {};
+  const chunks = [];
+  let totalBytes = 0;
+  const limit = Number.isFinite(maxResponseBytes) && maxResponseBytes > 0
+    ? Math.floor(maxResponseBytes)
+    : 262_144;
+  // EventEmitter shape: handlers like the Even-AI endpoint subscribe to
+  // res.once('close', ...) for client-disconnect detection. Worker-mode
+  // relays actual client closes through an http.cancel worker message.
+  const res = new EventEmitter();
+  res.statusCode = 200;
+  res.writableEnded = false;
+  res.setHeader = function (name, value) {
+    if (typeof name === "string" && name) {
+      headers[name.toLowerCase()] = value;
+    }
+  };
+  res.getHeader = function (name) {
+    return typeof name === "string" ? headers[name.toLowerCase()] : undefined;
+  };
+  res.write = function (chunk) {
+    if (this.writableEnded) return false;
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk ?? ""));
+    totalBytes += buffer.length;
+    if (totalBytes > limit) {
+      throw new Error("Buffered HTTP response exceeded relay worker limit");
+    }
+    chunks.push(buffer);
+    return true;
+  };
+  res.end = function (chunk) {
+    if (chunk !== undefined && chunk !== null) {
+      this.write(chunk);
+    }
+    this.writableEnded = true;
+  };
+  res.toResult = function () {
+    return {
+      statusCode: this.statusCode,
+      headers: { ...headers },
+      body: Buffer.concat(chunks),
+    };
+  };
+  return res;
 }
 
 // --- Factory ---
@@ -283,9 +338,7 @@ function createRelay(opts) {
   const activityStatusAdapter = createActivityStatusAdapter(
     opts.activityStatusAdapter,
   );
-  const ownedHttpServer =
-    !opts.httpServer && opts.evenAiEnabled === true ? createOwnedRelayHttpServer() : null;
-  const sharedHttpServer = opts.httpServer || ownedHttpServer || null;
+  const sharedHttpServer = opts.httpServer || null;
 
   // --- Cached state ---
 
@@ -298,6 +351,8 @@ function createRelay(opts) {
   let cachedStatus = null;
   /** Monotonic status snapshot revision used for resume handshake. */
   let statusRevision = 0;
+  /** @type {{sessionKey: string, modelProvider: string|null, model: string|null, thinkingLevel: string, reasoningLevel: string, verboseLevel: string}|null} */
+  let currentSessionModelConfigSnapshot = null;
 
   /** Relay-local deterministic simulate-stream run sequence counter. */
   let simulateStreamRunSeq = 0;
@@ -306,18 +361,48 @@ function createRelay(opts) {
 
   // --- Structured debug state ---
 
+  const debugCategories = Array.isArray(opts.debugCategories)
+    ? opts.debugCategories
+    : opts.debugCategories && typeof opts.debugCategories === "object"
+      ? Object.entries(opts.debugCategories)
+          .filter(([, enabled]) => enabled)
+          .map(([category]) => category)
+      : opts.debugCategories;
+  // Single relay-side clock: the debug store, the emitDebug ts stamp, and the
+  // liveui log tee all read from this one source so store records and `[liveui]`
+  // log lines share an identical ts (downstream reconcilers dedupe on it).
+  const debugNow =
+    typeof opts.debugNow === "function" ? opts.debugNow : () => Date.now();
   const debugStore = createDebugStore({
-    categories: opts.debugCategories,
+    categories: debugCategories,
     capacity: opts.debugCapacity,
     payloadMaxBytes: opts.debugPayloadMaxBytes,
     defaultTtlMs: opts.debugDefaultTtlMs,
     maxTtlMs: opts.debugMaxTtlMs,
     dumpDefaultLimit: opts.debugDumpDefaultLimit,
     dumpMaxLimit: opts.debugDumpMaxLimit,
-    now: opts.debugNow,
+    now: debugNow,
     noisyPolicies: opts.debugNoisyPolicies,
   });
 
+  // --- Live-interface trace-log flag (durable across restarts) ---
+  // Gates the glasses.lifecycle → gateway-log tee. Read once at construction;
+  // toggled live by applyTraceLogSet, which also rewrites this file so the
+  // value survives a relay/gateway restart (the store's enable-state does not).
+  const liveUiTraceFlagPath =
+    typeof opts.stateDir === "string" && opts.stateDir
+      ? path.join(opts.stateDir, "liveui-trace.json")
+      : null;
+  let liveUiTraceLogEnabled = false;
+  if (liveUiTraceFlagPath) {
+    try {
+      liveUiTraceLogEnabled =
+        JSON.parse(fs.readFileSync(liveUiTraceFlagPath, "utf8")).enabled === true;
+    } catch {
+      liveUiTraceLogEnabled = false;
+    }
+  }
+
   // --- Console log file ---
 
   const consoleLogPath =
@@ -371,8 +456,11 @@ 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) && !(liveUiTraceLogEnabled && (cat === "glasses.lifecycle" || cat === "openclaw.message"))) {
+      return;
+    }
 
     let data = {};
     if (typeof buildData === "function") {
@@ -383,18 +471,55 @@ function createRelay(opts) {
       }
     }
 
-    const payload = {
-      cat,
-      event,
-      severity,
-      data,
-    };
+    const ts = debugNow();
+    const payload = { ts, cat, event, severity, data };
 
     if (context && context.sessionKey) payload.sessionKey = context.sessionKey;
     if (context && context.runId) payload.runId = context.runId;
     if (context && context.screen) payload.screen = context.screen;
 
-    debugStore.emit(payload);
+    debugStore.emit(payload, { force });
+
+    // Durable openclaw-side trace tee (gated by the persistent flag, NOT the
+    // store category enable). Must never throw into the emit path.
+    if (liveUiTraceLogEnabled && (cat === "glasses.lifecycle" || cat === "openclaw.message")) {
+      try {
+        const surfaceId =
+          data && typeof data.surfaceId === "string" ? data.surfaceId : null;
+        const sessionKey =
+          payload.sessionKey ||
+          (data && typeof data.sessionKey === "string" ? data.sessionKey : null) ||
+          null;
+        const side =
+          cat === "openclaw.message"
+            ? (event === "user_message" ? "user" : "agent")
+            : "openclaw";
+        logger.info(
+          "[liveui] " +
+            JSON.stringify({
+              trace: "liveui",
+              side,
+              ts,
+              cat,
+              event,
+              severity,
+              surfaceId,
+              sessionKey,
+              data,
+            }),
+        );
+      } catch {
+        // observability must never break the emit path
+      }
+    }
+  }
+
+  function isForcedReadinessProofEvent(payload) {
+    return !!(
+      payload &&
+      payload.cat === "app.lifecycle" &&
+      payload.event === "readiness_probe_received"
+    );
   }
 
   function scheduleSimulateStreamTimer(delayMs, callback) {
@@ -430,6 +555,11 @@ function createRelay(opts) {
   )
     ? Math.max(30, Math.floor(opts.sonioxTemporaryKeyExpiresInSeconds))
     : DEFAULT_SONIOX_TEMP_KEY_EXPIRES_IN_SECONDS;
+  const sonioxTemporaryKeyMintTimeoutMs = Number.isFinite(
+    opts.sonioxTemporaryKeyMintTimeoutMs,
+  )
+    ? Math.max(1, Math.floor(opts.sonioxTemporaryKeyMintTimeoutMs))
+    : DEFAULT_SONIOX_TEMP_KEY_MINT_TIMEOUT_MS;
   /** @type {Array<{id: string, name: string, supportsMaxEndpointDelay: boolean}>|null} */
   let cachedSonioxModels = null;
   let cachedSonioxModelsFetchedAt = 0;
@@ -658,18 +788,29 @@ function createRelay(opts) {
         throw new Error("fetch is not available for Soniox temporary-key minting");
       }
 
-      const response = await fetchImpl(SONIOX_TEMP_KEY_URL, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${configuredSonioxApiKey}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          usage_type: "transcribe_websocket",
-          expires_in_seconds: sonioxTemporaryKeyExpiresInSeconds,
-          client_reference_id: voiceSessionId,
-        }),
-      });
+      const mintAbortController = new AbortController();
+      const mintTimeoutTimer = setTimeout(
+        () => mintAbortController.abort(),
+        sonioxTemporaryKeyMintTimeoutMs,
+      );
+      let response;
+      try {
+        response = await fetchImpl(SONIOX_TEMP_KEY_URL, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${configuredSonioxApiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            usage_type: "transcribe_websocket",
+            expires_in_seconds: sonioxTemporaryKeyExpiresInSeconds,
+            client_reference_id: voiceSessionId,
+          }),
+          signal: mintAbortController.signal,
+        });
+      } finally {
+        clearTimeout(mintTimeoutTimer);
+      }
 
       const rawText =
         response && typeof response.text === "function"
@@ -755,11 +896,63 @@ function createRelay(opts) {
     },
   });
 
-  function currentOcuClawSendOptions() {
+  function currentOcuClawSendOptions(perTurnSignals) {
+    const signals = perTurnSignals || {};
+    const baseReadability = composeReadabilitySystemPrompt(
+      ocuClawSettingsStore.getSnapshot().systemPrompt,
+    );
+    const validState = (raw) =>
+      raw === "active" || raw === "recently-disabled" || raw === "inactive"
+        ? raw
+        : "inactive";
+    const reactorState = validState(signals.neuralEmojiReactorState);
+    const paceState = validState(signals.neuralPaceModulatorState);
+    const reactor = composeNeuralEmojiReactorSystemPrompt({ state: reactorState });
+    const pace = composeNeuralPaceModulatorSystemPrompt({ state: paceState });
+    // Only include the glasses-UI nudge when a downstream app client is
+    // connected. Keeps the prompt clean when the agent has nowhere to render
+    // the tool's output, and keeps existing prompt-assembly tests stable
+    // (they exercise the prompt without spinning up an app client).
+    const hasAppClient =
+      server &&
+      typeof server.getConnectedAppCount === "function" &&
+      server.getConnectedAppCount() > 0;
+    const glassesUiNudge = hasAppClient ? composeGlassesUiNudgeSystemPrompt() : "";
+    const parts = [];
+    if (baseReadability) parts.push(baseReadability);
+    if (reactor) parts.push(reactor);
+    if (pace) parts.push(pace);
+    if (glassesUiNudge) parts.push(glassesUiNudge);
     return {
-      extraSystemPrompt: composeReadabilitySystemPrompt(
-        ocuClawSettingsStore.getSnapshot().systemPrompt,
-      ),
+      extraSystemPrompt: parts.join("\n\n"),
+    };
+  }
+
+  function buildOcuClawSendDiagnostic(params = {}) {
+    const attachment = params.attachment || null;
+    const messageId =
+      typeof params.id === "string" && params.id.trim()
+        ? params.id.trim()
+        : null;
+    const sessionKey =
+      typeof params.sessionKey === "string" && params.sessionKey.trim()
+        ? params.sessionKey.trim()
+        : sessionService.ensureSessionKey();
+    const source =
+      typeof params.source === "string" && params.source.trim()
+        ? params.source.trim()
+        : "relay_send";
+
+    return {
+      messageId,
+      sessionKey,
+      source,
+      textChars: typeof params.text === "string" ? params.text.length : 0,
+      hasAttachment: !!attachment,
+      attachmentBytes:
+        attachment && Number.isFinite(attachment.sizeBytes)
+          ? Math.floor(attachment.sizeBytes)
+          : null,
     };
   }
 
@@ -806,6 +999,9 @@ function createRelay(opts) {
     ) {
       patch.thinkingLevel = settings.defaultThinking.trim().toLowerCase();
     }
+    if (settings && settings.defaultFastMode === true) {
+      patch.fastMode = true;
+    }
     return Object.keys(patch).length > 0 ? patch : null;
   }
 
@@ -879,10 +1075,108 @@ 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,
+    onSessionModelConfig(config) {
+      applyCurrentSessionModelConfigSnapshot(config);
+    },
+    broadcastSessions: () => broadcastSessions(),
+    broadcastEvenAiSessions: () => broadcastEvenAiSessions(),
+  });
+
+  const relayHealth = createRelayHealthMonitor({
+    emitDebug(event, severity, data) {
+      emitDebug(
+        "relay.health",
+        event,
+        severity,
+        { sessionKey: sessionService.peekSessionKey() || undefined },
+        () => data,
+        { force: event === "relay_queue_depth" },
+      );
+    },
   });
+  relayHealth.start();
+
+  const relayOperationRegistry = createRelayOperationRegistry({
+    emitDebug(event, severity, data, context = {}) {
+      emitDebug(
+        "relay.operation",
+        event,
+        severity,
+        {
+          sessionKey: context.sessionKey || sessionService.peekSessionKey() || undefined,
+          runId: context.runId || undefined,
+        },
+        () => data,
+      );
+    },
+  });
+
+  function isActiveSessionModelConfig(config) {
+    return !!(
+      config &&
+      typeof config.sessionKey === "string" &&
+      (
+        typeof sessionService.isCurrentSession === "function"
+          ? sessionService.isCurrentSession(config.sessionKey)
+          : config.sessionKey === sessionService.ensureSessionKey()
+      )
+    );
+  }
+
+  function applyCurrentSessionModelConfigSnapshot(config) {
+    if (!isActiveSessionModelConfig(config)) {
+      return false;
+    }
+    currentSessionModelConfigSnapshot = config;
+    if (
+      upstreamRuntime &&
+      typeof upstreamRuntime.handleCurrentSessionModelConfigChanged === "function"
+    ) {
+      upstreamRuntime.handleCurrentSessionModelConfigChanged().catch((err) => {
+        logger.warn(`[relay] Provider usage rebroadcast failed after session config update: ${err.message}`);
+      });
+    }
+    return true;
+  }
+
+  function clearCurrentSessionModelConfigSnapshot(trigger) {
+    currentSessionModelConfigSnapshot = null;
+    if (
+      upstreamRuntime &&
+      typeof upstreamRuntime.handleCurrentSessionModelConfigCleared === "function"
+    ) {
+      upstreamRuntime.handleCurrentSessionModelConfigCleared().catch((err) => {
+        logger.warn(`[relay] Provider usage clear broadcast failed after ${trigger}: ${err.message}`);
+      });
+    }
+  }
+
+  // TTL fallback for set_session_title activity label. The tool itself
+  // completes in <50ms but its label can linger if no follow-up activity
+  // arrives (e.g. agent streams a response directly after, with no
+  // intervening activity event). After 1s, synthesize a thinking-status
+  // activity with no tool/label so the renderer falls back to the bare
+  // animated spinner. Any real activity arriving in the meantime cancels
+  // the timer.
+  const SESSION_TITLE_STATUS_FALLBACK_MS = 1500;
+  let sessionTitleStatusFallbackTimer = null;
 
   function broadcastActivity(rawActivity) {
     const activity = activityStatusAdapter.augmentActivity(rawActivity || {});
@@ -905,6 +1199,8 @@ function createRelay(opts) {
         intent: (activity && activity.intent) || null,
         thinkingSummarySource: (activity && activity.thinkingSummarySource) || null,
         category: (activity && activity.category) || null,
+        isError: typeof activity.isError === "boolean" ? activity.isError : null,
+        code: (activity && activity.code) || null,
         activityId: (activity && activity.activityId) || null,
         seq: Number.isFinite(activity && activity.seq) ? activity.seq : null,
         origin,
@@ -913,9 +1209,194 @@ function createRelay(opts) {
     );
 
     server.broadcast(handler.formatActivity(activity));
+
+    if (sessionTitleStatusFallbackTimer) {
+      clearTimeout(sessionTitleStatusFallbackTimer);
+      sessionTitleStatusFallbackTimer = null;
+    }
+    if (
+      activity &&
+      activity.tool === "set_session_title" &&
+      phase !== "end" &&
+      origin !== "synthetic_session_title_fallback"
+    ) {
+      const fallbackSessionKey = activity.sessionKey || null;
+      const fallbackRunId = runId;
+      sessionTitleStatusFallbackTimer = setTimeout(() => {
+        sessionTitleStatusFallbackTimer = null;
+        broadcastActivity({
+          state: "thinking",
+          sessionKey: fallbackSessionKey,
+          runId: fallbackRunId,
+          origin: "synthetic_session_title_fallback",
+          phase: "update",
+        });
+      }, SESSION_TITLE_STATUS_FALLBACK_MS);
+    }
+
     return activity;
   }
 
+  function broadcastProviderUsageSnapshot(snapshot) {
+    if (!server || !handler || typeof handler.formatProviderUsageSnapshot !== "function") {
+      return snapshot;
+    }
+    server.broadcast(handler.formatProviderUsageSnapshot(snapshot || {}));
+    return snapshot;
+  }
+
+  const appClientDisconnectHandlers = new Set();
+  function onAppClientDisconnect(handler) {
+    if (typeof handler !== "function") return () => {};
+    appClientDisconnectHandlers.add(handler);
+    return () => appClientDisconnectHandlers.delete(handler);
+  }
+  function dispatchAppClientDisconnect(sessionKey) {
+    for (const handler of appClientDisconnectHandlers) {
+      try { handler({ sessionKey }); } catch (err) {
+        logger.warn(`[relay] app_client_disconnect handler threw: ${err && err.message ? err.message : err}`);
+      }
+    }
+  }
+
+  const glassesUiResultHandlers = new Set();
+
+  function sendGlassesUiRender(params) {
+    if (!server) return;
+    const payload = {
+      type: "glasses_ui_render",
+      sessionKey: params && typeof params.sessionKey === "string" ? params.sessionKey : null,
+      surfaceId: params && typeof params.surfaceId === "string" ? params.surfaceId : "",
+      depth: Number.isFinite(params && params.depth) ? Math.floor(params.depth) : 1,
+      spec: params && params.spec ? params.spec : null,
+    };
+    server.broadcast(JSON.stringify(payload));
+    emitDebug(
+      "glasses.lifecycle",
+      "surface_send",
+      "debug",
+      { sessionKey: payload.sessionKey || undefined },
+      () => ({ surfaceId: payload.surfaceId, mode: "render", depth: payload.depth, ...summarizeGlassesUiContent(payload.spec) }),
+    );
+  }
+
+  function sendGlassesUiSurfaceUpdate(params) {
+    if (!server) return;
+    const patch = params && params.patch ? params.patch : null;
+    if (!patch) return;
+    const cleanPatch = {};
+    if (typeof patch.title === "string") cleanPatch.title = patch.title;
+    if (typeof patch.body === "string") cleanPatch.body = patch.body;
+    if (Array.isArray(patch.items)) {
+      // Items may be plain-string labels (list_surface / label-only) OR
+      // {label, body} objects (list_with_details detail-body ticks). Keep both
+      // shapes; drop anything malformed (no string, no string label).
+      cleanPatch.items = patch.items
+        .map((i) => {
+          if (typeof i === "string") return i;
+          if (i && typeof i === "object" && typeof i.label === "string") {
+            const o = { label: i.label };
+            if (typeof i.body === "string") o.body = i.body;
+            return o;
+          }
+          return null;
+        })
+        .filter((i) => i !== null);
+    }
+    const payload = {
+      type: "glasses_ui_surface_update",
+      sessionKey: params && typeof params.sessionKey === "string" ? params.sessionKey : null,
+      surfaceId: params && typeof params.surfaceId === "string" ? params.surfaceId : "",
+      patch: cleanPatch,
+    };
+    server.broadcast(JSON.stringify(payload));
+    emitDebug(
+      "glasses.lifecycle",
+      "surface_send",
+      "debug",
+      { sessionKey: payload.sessionKey || undefined },
+      () => ({ surfaceId: payload.surfaceId, mode: "update", ...summarizeGlassesUiContent(cleanPatch) }),
+    );
+  }
+
+  function onGlassesUiResult(handler) {
+    if (typeof handler !== "function") return () => {};
+    glassesUiResultHandlers.add(handler);
+    return () => glassesUiResultHandlers.delete(handler);
+  }
+
+  function dispatchGlassesUiResult(frame) {
+    if (!frame || typeof frame !== "object") return;
+    for (const handler of glassesUiResultHandlers) {
+      try {
+        handler({
+          surfaceId: typeof frame.surfaceId === "string" ? frame.surfaceId : "",
+          outcome: frame.outcome,
+        });
+      } catch (err) {
+        logger.warn(`[relay] glasses_ui_result handler threw: ${err.message}`);
+      }
+    }
+  }
+
+  const glassesUiNavEventHandlers = new Set();
+
+  function onGlassesUiNavEvent(handler) {
+    if (typeof handler !== "function") return () => {};
+    glassesUiNavEventHandlers.add(handler);
+    return () => glassesUiNavEventHandlers.delete(handler);
+  }
+
+  function dispatchGlassesUiNavEvent(frame) {
+    if (!frame || typeof frame !== "object") return;
+    for (const handler of glassesUiNavEventHandlers) {
+      try {
+        handler({
+          surfaceId: typeof frame.surfaceId === "string" ? frame.surfaceId : "",
+          depth: Number.isFinite(frame.depth) ? Math.max(1, Math.floor(frame.depth)) : 1,
+        });
+      } catch (err) {
+        logger.warn(`[relay] glasses_ui_nav_event handler threw: ${err.message}`);
+      }
+    }
+  }
+
+  const deviceInfoResponseHandlers = new Set();
+
+  function sendDeviceInfoRequest(params) {
+    if (!server) return;
+    const payload = {
+      type: "device_info_request",
+      sessionKey: params && typeof params.sessionKey === "string" ? params.sessionKey : null,
+      requestId: params && typeof params.requestId === "string" ? params.requestId : "",
+    };
+    server.broadcast(JSON.stringify(payload));
+  }
+
+  function onDeviceInfoResponse(handler) {
+    if (typeof handler !== "function") return () => {};
+    deviceInfoResponseHandlers.add(handler);
+    return () => deviceInfoResponseHandlers.delete(handler);
+  }
+
+  function dispatchDeviceInfoResponse(frame) {
+    if (!frame || typeof frame !== "object") return;
+    for (const handler of deviceInfoResponseHandlers) {
+      try {
+        handler({
+          requestId: typeof frame.requestId === "string" ? frame.requestId : "",
+          ok: frame.ok === true,
+          code: typeof frame.code === "string" ? frame.code : undefined,
+          data: frame.data && typeof frame.data === "object" ? frame.data : undefined,
+        });
+      } catch (err) {
+        logger.warn(
+          `[relay] device_info_response handler threw: ${err && err.message ? err.message : err}`,
+        );
+      }
+    }
+  }
+
   function normalizeAttachmentErrorCode(err) {
     if (!err) return "attachment_upstream_rejected";
     const code = typeof err.code === "string" ? err.code.trim() : "";
@@ -948,10 +1429,18 @@ function createRelay(opts) {
     const text = params.text;
     const sessionKey = params.sessionKey;
     const attachment = params.attachment || null;
+    const clientDisplaySignals = params.clientDisplaySignals || null;
     const resolvedSessionKey = sessionKey || sessionService.ensureSessionKey();
     sessionService.recordFirstSentUserMessage(resolvedSessionKey, text);
+    if (clientDisplaySignals && resolvedSessionKey) {
+      sessionService.recordNeuralSessionNamesEnabled(
+        resolvedSessionKey,
+        clientDisplaySignals.neuralSessionNamesEnabled !== false,
+      );
+    }
     const hasAttachment = !!attachment;
     const sendStartedAt = Date.now();
+    relayOperationRegistry.markStarted(id);
     sessionService.invalidateSessionsCache();
     emitDebug(
       "relay.protocol",
@@ -976,13 +1465,24 @@ function createRelay(opts) {
         text,
         resolvedSessionKey,
         attachment,
-        currentOcuClawSendOptions(),
+        {
+          ...currentOcuClawSendOptions(clientDisplaySignals),
+          diagnostic: buildOcuClawSendDiagnostic({
+            ...params,
+            sessionKey: resolvedSessionKey,
+          }),
+        },
       );
       const upstreamDispatchedAt = Date.now();
 
-      conversationState.addMessage(
-        "user",
-        buildLocalUserMessageContent(text, attachment),
+      const userContent = buildLocalUserMessageContent(text, attachment);
+      conversationState.addMessage("user", userContent);
+      emitDebug(
+        "openclaw.message",
+        "user_message",
+        "info",
+        { sessionKey: resolvedSessionKey },
+        () => ({ text: typeof text === "string" ? text : "" }),
       );
       broadcastPages();
       const localPublishDoneAt = Date.now();
@@ -1005,6 +1505,10 @@ function createRelay(opts) {
         (result) => {
           const ackAt = Date.now();
           const runId = result && result.runId ? result.runId : null;
+          relayOperationRegistry.markUpstreamAck(id, {
+            runId,
+            status: result && result.status ? result.status : null,
+          });
           if (runId && upstreamRuntime) {
             upstreamRuntime.trackAcceptedRun({
               runId,
@@ -1030,8 +1534,16 @@ function createRelay(opts) {
           return result;
         },
         (err) => {
-          if (attachment && !err.errorCode) {
-            err.errorCode = normalizeAttachmentErrorCode(err);
+          const mirroredErrorCode =
+            err && typeof err.errorCode === "string" && err.errorCode.trim()
+              ? err.errorCode.trim()
+              : err && typeof err.code === "string" && err.code.trim()
+                ? err.code.trim()
+                : attachment
+                  ? normalizeAttachmentErrorCode(err)
+                  : null;
+          if (mirroredErrorCode && err && typeof err === "object") {
+            err.errorCode = mirroredErrorCode;
           }
           emitDebug(
             "relay.protocol",
@@ -1042,7 +1554,8 @@ function createRelay(opts) {
               messageId: id,
               elapsedMs: Date.now() - sendStartedAt,
               hasAttachment,
-              errorCode: err.errorCode || null,
+              errorCode:
+                err && typeof err.errorCode === "string" ? err.errorCode : null,
               message: err && err.message ? err.message : String(err),
             }),
           );
@@ -1074,13 +1587,39 @@ function createRelay(opts) {
     };
   }
 
+  function emitListenInterceptBroadcast(params = {}) {
+    if (!server || !handler) {
+      return;
+    }
+    const sessionKey = params && typeof params.sessionKey === "string" ? params.sessionKey : null;
+    server.broadcast(handler.formatEvenAiListenIntercepted(sessionKey));
+  }
+
   // --- Downstream handler ---
 
-  /** @type {ReturnType<typeof createDownstreamServer>|null} */
+  /** @type {ReturnType<typeof createRelayWorkerSupervisor>|null} */
   let server = null;
   let evenAiEndpoint = null;
   let evenAiRouter = null;
   let evenAiRunWaiter = null;
+  const pendingBufferedEvenAiResponses = new Map();
+  let relayApi = null;
+
+  function applyTraceLogSet(clientId, request) {
+    const enabled = !!(request && request.enabled === true);
+    liveUiTraceLogEnabled = enabled;
+    let persisted = false;
+    if (liveUiTraceFlagPath) {
+      try {
+        fs.writeFileSync(liveUiTraceFlagPath, JSON.stringify({ enabled }) + "\n");
+        persisted = true;
+      } catch (err) {
+        logger.warn(`[relay] liveui trace-log flag persist failed: ${err && err.message ? err.message : err}`);
+      }
+    }
+    emitDebug("relay.protocol", "trace_log_set", "info", { sessionKey: sessionService.ensureSessionKey() }, () => ({ clientId, enabled, persisted }));
+    return { ok: true, enabled, persisted, persistedPath: liveUiTraceFlagPath };
+  }
 
   const handler = createDownstreamHandler({
     logger,
@@ -1099,14 +1638,99 @@ function createRelay(opts) {
      * @param {object|null} attachment - Optional image attachment payload
      * @returns {Promise}
      */
-    onSend(id, text, sessionKey, attachment) {
+    onSend(id, text, sessionKey, attachment, clientDisplaySignals) {
       return dispatchOcuClawUserSend({
         id,
         text,
         sessionKey,
         attachment,
+        clientDisplaySignals: clientDisplaySignals || null,
+        source: "phone_ui",
       });
     },
+    onGlassesUiResult(frame) {
+      emitDebug(
+        "glasses.lifecycle",
+        "surface_outcome",
+        "debug",
+        {},
+        () => ({ surfaceId: frame && frame.surfaceId, outcome: frame && frame.outcome }),
+      );
+      dispatchGlassesUiResult(frame);
+    },
+    onGlassesUiNavEvent(frame) {
+      emitDebug(
+        "glasses.lifecycle",
+        "nav_event_recv",
+        "debug",
+        {},
+        () => ({ surfaceId: frame && frame.surfaceId, depth: frame && frame.depth }),
+      );
+      dispatchGlassesUiNavEvent(frame);
+    },
+    onDeviceInfoResponse(frame) {
+      dispatchDeviceInfoResponse(frame);
+    },
+    onGlassesUiRenderInject(params) {
+      sendGlassesUiRender(params);
+    },
+    onSetUserSessionTitle(sessionKey, title) {
+      const result = sessionService.setSessionTitle(sessionKey, title, { userSet: true });
+      if (result && result.ok) {
+        broadcastSessions();
+      }
+    },
+    onSetSessionPinned(sessionKey, pinned, kind) {
+      const result = sessionService.setSessionPinned(kind, sessionKey, pinned);
+      if (result && result.ok) {
+        broadcastSessions();
+      }
+      return result;
+    },
+    onCompactSession({ sessionKey }) {
+      if (!upstreamRuntime || typeof upstreamRuntime.compactActiveSession !== "function") {
+        return Promise.resolve({
+          status: "rejected",
+          error: "upstream runtime not ready",
+        });
+      }
+      return upstreamRuntime.compactActiveSession(sessionKey);
+    },
+    onDeleteSessions(sessionKeys, kind, switchBeforeDelete) {
+      const action = switchBeforeDelete
+        ? sessionService.switchAndDeleteSessions(kind, sessionKeys)
+        : sessionService.deleteSessions(kind, sessionKeys);
+      Promise.resolve(action)
+        .then(() => broadcastSessions())
+        .catch((err) => {
+          logger.error(`[relay] deleteSessions failed: ${err && err.message ? err.message : err}`);
+        });
+    },
+    onSearchTranscripts(clientId, query, kind) {
+      Promise.resolve(sessionService.searchTranscripts(kind, query))
+        .then((result) => {
+          if (!server) return;
+          const payload = {
+            type: "ocuclaw.session.transcripts.search.result",
+            query,
+            kind,
+            snippets: result.snippets,
+            truncated: result.truncated,
+          };
+          server.unicast(clientId, JSON.stringify(payload));
+        })
+        .catch((err) => {
+          logger.error(`[relay] searchTranscripts failed: ${err && err.message ? err.message : err}`);
+          if (server) {
+            const payload = {
+              type: "ocuclaw.session.transcripts.search.result",
+              query, kind, snippets: [], truncated: false,
+            };
+            server.unicast(clientId, JSON.stringify(payload));
+          }
+        });
+    },
+    operationRegistry: relayOperationRegistry,
 
     /**
      * Inject a fake assistant message into conversation state.
@@ -1262,6 +1886,9 @@ function createRelay(opts) {
         { sessionKey: sessionService.ensureSessionKey() },
         () => ({}),
       );
+      if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
+        upstreamRuntime.clearTyping("new_chat");
+      }
       sessionService.invalidateSessionsCache();
       resetActivityStatusAdapter();
       conversationState.clear();
@@ -1284,6 +1911,10 @@ function createRelay(opts) {
 
     onSwitchSession(sessionKey) {
       return sessionService.switchToSession(sessionKey).then((pages) => {
+        clearCurrentSessionModelConfigSnapshot("switch_session");
+        if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
+          upstreamRuntime.clearTyping("switch_session");
+        }
         if (upstreamRuntime && typeof upstreamRuntime.handleSessionChanged === "function") {
           upstreamRuntime.handleSessionChanged("switch_session");
         }
@@ -1293,6 +1924,10 @@ function createRelay(opts) {
 
     async onNewSession() {
       const result = await sessionService.newSession();
+      clearCurrentSessionModelConfigSnapshot("new_session");
+      if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
+        upstreamRuntime.clearTyping("new_session");
+      }
       if (upstreamRuntime && typeof upstreamRuntime.handleSessionChanged === "function") {
         upstreamRuntime.handleSessionChanged("new_session");
       }
@@ -1319,12 +1954,26 @@ function createRelay(opts) {
         : Promise.resolve({ skills: [], fetchedAtMs: Date.now(), stale: true });
     },
 
+    onGetProviderUsageSnapshot() {
+      return upstreamRuntime
+        ? upstreamRuntime.getProviderUsageSnapshot()
+        : Promise.resolve({
+            sessionKey: null,
+            provider: null,
+            displayName: null,
+            limitingWindowKey: null,
+            windows: [],
+            fetchedAtMs: Date.now(),
+            stale: true,
+          });
+    },
+
     onGetSonioxModels() {
       return getSonioxModelsSnapshot();
     },
 
     onGetStatus() {
-      return buildStatusObject();
+      return buildStatusObject({ includeDownstreamReadiness: true });
     },
 
     onGetSessionModelConfig() {
@@ -1333,7 +1982,13 @@ function createRelay(opts) {
 
     async onSetSessionModelConfig(patch) {
       const result = await sessionService.setCurrentSessionModelConfig(patch || {});
-      if (result && result.status === "accepted" && result.config) {
+      if (
+        result &&
+        result.status === "accepted" &&
+        result.config &&
+        isActiveSessionModelConfig(result.config)
+      ) {
+        currentSessionModelConfigSnapshot = result.config;
         server.broadcast(handler.formatSessionModelConfig(result.config));
       }
       return result;
@@ -1348,50 +2003,7 @@ function createRelay(opts) {
     },
 
     async onGetEvenAiSessions() {
-      const dedicatedKey =
-        evenAiRouter && typeof evenAiRouter.getDedicatedSessionKey === "function"
-          ? evenAiRouter.getDedicatedSessionKey()
-          : opts.evenAiDedicatedSessionKey;
-      const dedicatedEvenAiKey = normalizeEvenAiSessionKeyForLookup(dedicatedKey);
-      const trackedThrowawayKeys =
-        typeof evenAiSettingsStore.getTrackedThrowawayKeys === "function"
-          ? evenAiSettingsStore.getTrackedThrowawayKeys()
-          : [];
-      const normalizedTrackedThrowawayKeys = dedupeNormalizedSessionKeys(
-        trackedThrowawayKeys,
-      );
-      const resolvedSessions = await sessionService.getSessionsByExactKeys([
-        ...normalizedTrackedThrowawayKeys,
-        ...(dedicatedEvenAiKey ? [dedicatedEvenAiKey] : []),
-      ]);
-      const normalizedDedicatedKey = dedicatedEvenAiKey.toLowerCase();
-      const sessions = [];
-      let dedicatedIncluded = false;
-      for (const session of resolvedSessions) {
-        if (
-          !dedicatedIncluded &&
-          session &&
-          typeof session.key === "string" &&
-          session.key.trim().toLowerCase() === normalizedDedicatedKey
-        ) {
-          sessions.push(session);
-          dedicatedIncluded = true;
-          continue;
-        }
-        sessions.push(session);
-      }
-      if (!dedicatedIncluded && dedicatedEvenAiKey) {
-        sessions.unshift({
-          key: dedicatedEvenAiKey,
-          updatedAt: 0,
-          preview: "",
-          firstUserMessage: "",
-        });
-      }
-      return {
-        sessions,
-        dedicatedKey,
-      };
+      return buildEvenAiSessionsSnapshot();
     },
 
     async onSetEvenAiSettings(patch) {
@@ -1422,6 +2034,9 @@ function createRelay(opts) {
         sessionService.invalidateSessionsCache();
         resetActivityStatusAdapter();
         conversationState.clear();
+        if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
+          upstreamRuntime.clearTyping("slash_reset");
+        }
         conversationState.setAgentName(
           (upstreamRuntime ? upstreamRuntime.getAgentName() : null) || "Agent",
         );
@@ -1437,7 +2052,7 @@ function createRelay(opts) {
      * @returns {boolean} Whether upstream is connected.
      */
     isUpstreamConnected() {
-      return upstreamRuntime ? upstreamRuntime.isConnected() : false;
+      return true;
     },
 
     onConsoleLog(level, message) {
@@ -1459,7 +2074,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 +2089,7 @@ function createRelay(opts) {
           clientId,
           ...(payload.data || {}),
         }),
+        { force: forceStore },
       );
     },
 
@@ -1507,6 +2124,13 @@ function createRelay(opts) {
       return result;
     },
 
+    onTraceLogSet(clientId, request) {
+      return applyTraceLogSet(clientId, request);
+    },
+    onTraceLogGet() {
+      return { ok: true, enabled: liveUiTraceLogEnabled, persistedPath: liveUiTraceFlagPath };
+    },
+
     onDebugDump(clientId, request) {
       const result = debugStore.dump(request);
       if (!result.ok) {
@@ -1637,14 +2261,265 @@ 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,
+        },
+      };
+    },
+
+    onAutomationState(clientId, request) {
+      // Mirrors onReadinessProbe (above): identify the single connected app
+      // client via the readiness snapshot, then return a dispatch envelope
+      // that downstream-handler.handleAutomationState wraps into
+      // `automationStateRequest`. Without this callback wired, the handler
+      // returns null and the request is silently dropped at the relay —
+      // simctl/debugctl times out with no failure response, no trace event,
+      // no outbox drop. The lack of wiring was found 2026-05-28 while
+      // validating the streaming-thinking-emoji-demotion fix on the sim.
+      const now = Date.now();
+      const requestId =
+        (typeof request.requestId === "string" && request.requestId.trim()) ||
+        `automation-${now}-${Math.random().toString(16).slice(2, 8)}`;
+      const requestedSessionKey =
+        typeof request.sessionKey === "string" && request.sessionKey.trim()
+          ? request.sessionKey.trim()
+          : null;
+      const snapshot =
+        server && typeof server.getReadinessSnapshot === "function"
+          ? server.getReadinessSnapshot()
+          : {
+              connectedClientCount: 0,
+              fanoutRecipientCount: 0,
+              clients: [],
+            };
+      const targetEntry =
+        snapshot &&
+        snapshot.connectedClientCount === 1 &&
+        snapshot.fanoutRecipientCount === 1 &&
+        Array.isArray(snapshot.clients) &&
+        snapshot.clients.length === 1
+          ? snapshot.clients[0]
+          : null;
+      const targetClientId =
+        targetEntry && typeof targetEntry.clientId === "string"
+          ? targetEntry.clientId
+          : null;
+      // A connected app client that has never published a readiness snapshot
+      // cannot answer an automation state request; forwarding anyway would
+      // park the request in pendingAutomationStateRequests with no reply.
+      // Same predicate as the downstream readiness gate; this wired callback
+      // bypasses the normal dispatch path.
+      const readinessPublished =
+        !!(
+          targetEntry &&
+          targetEntry.readinessSnapshot &&
+          Number.isFinite(targetEntry.readinessSnapshot.emittedAtMs)
+        );
+
+      emitDebug(
+        "relay.protocol",
+        "automation_state_requested",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          requestedSessionKey,
+          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",
+        };
+      }
+
+      if (!readinessPublished) {
+        return {
+          ok: false,
+          requestId,
+          reasonCode: "snapshot_unavailable",
+          message: "Automation state snapshot is unavailable",
+        };
+      }
+
+      emitDebug(
+        "relay.protocol",
+        "automation_state_dispatched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          targetClientId,
+        }),
+      );
+
+      return {
+        ok: true,
+        requestId,
+        targetClientId,
+        request: {
+          requestId,
+          sessionKey: requestedSessionKey,
+        },
+      };
+    },
   });
 
-  // --- Downstream server ---
+  // --- Worker supervisor ---
 
-  server = createDownstreamServer({
+  const pluginUpdateService = createPluginUpdateService({
+    spawn: childProcess.spawn,
+    logger,
+    nowMs: () => Date.now(),
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+  });
+
+  server = createRelayWorkerSupervisor({
+    pluginId: "ocuclaw",
+    getPluginVersion: () => pluginUpdateService.getPluginVersion(),
+    getRequiresClientVersion: () => pluginUpdateService.getRequiresClientVersion(),
     logger,
-    externalDebugToolsEnabled,
     handler,
+    operationRegistry: relayOperationRegistry,
+    host: opts.host,
+    port: opts.port,
+    token: opts.token,
+    externalDebugToolsEnabled,
+    runPluginUpdate: () => pluginUpdateService.runPluginUpdate(),
+    runGatewayRestart: () => pluginUpdateService.runGatewayRestart(),
+    evenAiRequestTimeoutMs: opts.evenAiRequestTimeoutMs,
+    evenAiMaxBodyBytes: opts.evenAiMaxBodyBytes,
+    evenAiMaxResponseBytes: opts.evenAiMaxResponseBytes,
     getCurrentPages() {
       return cachedPages;
     },
@@ -1660,95 +2535,58 @@ function createRelay(opts) {
         statusRevision: statusRevision || 0,
       };
     },
-    onClientConnected(meta) {
-      emitDebug(
-        "relay.session",
-        "downstream_client_connected",
-        "info",
-        { sessionKey: sessionService.peekSessionKey() || undefined },
-        () => ({
-          clientId: meta && meta.clientId ? meta.clientId : null,
-          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
-          connectedAtMs: meta && Number.isFinite(meta.connectedAtMs) ? meta.connectedAtMs : null,
-          remoteAddress: meta && meta.remoteAddress ? meta.remoteAddress : null,
-          userAgentTail: meta && meta.userAgent ? meta.userAgent : null,
-        }),
-      );
+    getAgentAvatarHash: () =>
+      upstreamRuntime && typeof upstreamRuntime.getAgentAvatarHash === "function"
+        ? upstreamRuntime.getAgentAvatarHash()
+        : null,
+    getAgentAvatarDataUriByHash: (hash) =>
+      upstreamRuntime && typeof upstreamRuntime.getAgentAvatarDataUriByHash === "function"
+        ? upstreamRuntime.getAgentAvatarDataUriByHash(hash)
+        : null,
+    handleBufferedEvenAiHttpRequest(envelope) {
+      return handleBufferedEvenAiHttpRequest(envelope);
     },
-    onClientDisconnected(meta) {
-      emitDebug(
-        "relay.session",
-        "downstream_client_disconnected",
-        "info",
-        { sessionKey: sessionService.peekSessionKey() || undefined },
-        () => ({
-          clientId: meta && meta.clientId ? meta.clientId : null,
-          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
-          connectedAtMs: meta && Number.isFinite(meta.connectedAtMs) ? meta.connectedAtMs : null,
-          lifetimeMs: meta && Number.isFinite(meta.lifetimeMs) ? meta.lifetimeMs : null,
-          closeCode: meta && Number.isFinite(meta.closeCode) ? meta.closeCode : null,
-          closeReasonTail: meta && meta.closeReason ? meta.closeReason : null,
-          role: meta && meta.role ? meta.role : null,
-          clientKind: meta && meta.clientKind ? meta.clientKind : null,
-          protocolVersion: meta && meta.protocolVersion ? meta.protocolVersion : null,
-          protocolReason: meta && meta.protocolReason ? meta.protocolReason : null,
-          clientName: meta && meta.clientName ? meta.clientName : null,
-          clientVersion: meta && meta.clientVersion ? meta.clientVersion : null,
-          firstMessageType: meta && meta.firstMessageType ? meta.firstMessageType : null,
-          textMessageCount: meta && Number.isFinite(meta.textMessageCount) ? meta.textMessageCount : null,
-          binaryMessageCount: meta && Number.isFinite(meta.binaryMessageCount) ? meta.binaryMessageCount : null,
-          remoteControlCount: meta && Number.isFinite(meta.remoteControlCount) ? meta.remoteControlCount : null,
-        }),
-      );
+    cancelBufferedEvenAiHttpRequest(envelope) {
+      return cancelBufferedEvenAiHttpRequest(envelope);
     },
-    onTransportControl(meta) {
-      if (!meta || meta.controlType !== "visibility") {
-        return;
-      }
-      emitDebug(
-        "relay.session",
-        "downstream_transport_visibility",
-        "info",
-        { sessionKey: meta.sessionKey || sessionService.peekSessionKey() || undefined },
-        () => ({
-          clientId: meta && meta.clientId ? meta.clientId : null,
-          state: meta && meta.state ? meta.state : null,
-          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
-          role: meta && meta.role ? meta.role : null,
-          clientKind: meta && meta.clientKind ? meta.clientKind : null,
-          clientName: meta && meta.clientName ? meta.clientName : null,
-          clientVersion: meta && meta.clientVersion ? meta.clientVersion : null,
-          protocolVersion: meta && meta.protocolVersion ? meta.protocolVersion : null,
-        }),
-      );
+    getActiveSessionKey() {
+      return sessionService.peekSessionKey() || null;
+    },
+    onAppClientDisconnect(sessionKey) {
+      dispatchAppClientDisconnect(sessionKey);
+    },
+    emitDebug(category, event, severity, context, payloadFactory, options) {
+      emitDebug(category, event, severity, context, payloadFactory, options);
     },
-    httpServer: sharedHttpServer,
-    port: opts.port,
-    host: opts.host,
-    token: opts.token,
   });
-  if (ownedHttpServer) {
-    ownedHttpServer.on("listening", () => {
-      server.wss.emit("listening");
-    });
-    ownedHttpServer.on("error", (err) => {
-      server.wss.emit("error", err);
-    });
-    listenOwnedRelayHttpServer(ownedHttpServer, opts.host, opts.port);
-  }
 
   // --- Helpers ---
 
-  function buildStatusObject() {
-    return {
+  function buildStatusObject(options = {}) {
+    const includeDownstreamReadiness = options.includeDownstreamReadiness === true;
+    const status = {
       openclaw:
         upstreamRuntime && upstreamRuntime.isConnected()
           ? "connected"
           : "disconnected",
       agent: upstreamRuntime ? upstreamRuntime.getAgentName() : null,
+      agentEmoji: upstreamRuntime ? upstreamRuntime.getAgentEmoji() : null,
+      agentAvatarHash: upstreamRuntime ? upstreamRuntime.getAgentAvatarHash() : null,
       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) {
@@ -1782,6 +2620,97 @@ function createRelay(opts) {
     }
   }
 
+  /**
+   * Fetch the latest sessions snapshot and broadcast it. Used after a session
+   * title changes so connected clients refresh the title in the main webui
+   * status row and Session Settings tab without waiting for a manual
+   * session-list open.
+   */
+  function broadcastSessions() {
+    sessionService
+      .getSessions()
+      .then((sessions) => {
+        server.broadcast(handler.formatSessions(sessions));
+      })
+      .catch((err) => {
+        emitDebug(
+          "relay.session",
+          "session_broadcast_failed",
+          "debug",
+          { sessionKey: sessionService.peekSessionKey() || undefined },
+          () => ({ message: err && err.message ? err.message : String(err) }),
+        );
+      });
+  }
+
+  /**
+   * Resolve the current Even AI sessions snapshot for unicast/broadcast.
+   * Mirrors the shape that `formatEvenAiSessions` expects.
+   */
+  async function buildEvenAiSessionsSnapshot() {
+    const dedicatedKey =
+      evenAiRouter && typeof evenAiRouter.getDedicatedSessionKey === "function"
+        ? evenAiRouter.getDedicatedSessionKey()
+        : opts.evenAiDedicatedSessionKey;
+    const dedicatedEvenAiKey = normalizeEvenAiSessionKeyForLookup(dedicatedKey);
+    const trackedThrowawayKeys =
+      typeof evenAiSettingsStore.getTrackedThrowawayKeys === "function"
+        ? evenAiSettingsStore.getTrackedThrowawayKeys()
+        : [];
+    const normalizedTrackedThrowawayKeys = dedupeNormalizedSessionKeys(
+      trackedThrowawayKeys,
+    );
+    const resolvedSessions = await sessionService.getSessionsByExactKeys([
+      ...normalizedTrackedThrowawayKeys,
+      ...(dedicatedEvenAiKey ? [dedicatedEvenAiKey] : []),
+    ]);
+    const normalizedDedicatedKey = dedicatedEvenAiKey.toLowerCase();
+    const sessions = [];
+    let dedicatedIncluded = false;
+    for (const session of resolvedSessions) {
+      if (
+        !dedicatedIncluded &&
+        session &&
+        typeof session.key === "string" &&
+        session.key.trim().toLowerCase() === normalizedDedicatedKey
+      ) {
+        sessions.push(session);
+        dedicatedIncluded = true;
+        continue;
+      }
+      sessions.push(session);
+    }
+    if (!dedicatedIncluded && dedicatedEvenAiKey) {
+      sessions.unshift({
+        key: dedicatedEvenAiKey,
+        updatedAt: 0,
+        preview: "",
+        firstUserMessage: "",
+      });
+    }
+    return { sessions, dedicatedKey };
+  }
+
+  function broadcastEvenAiSessions() {
+    if (!server) return;
+    buildEvenAiSessionsSnapshot()
+      .then((payload) => {
+        server.broadcast(handler.formatEvenAiSessions(payload));
+      })
+      .catch((err) => {
+        emitDebug(
+          "relay.session",
+          "session_broadcast_failed",
+          "debug",
+          { sessionKey: sessionService.peekSessionKey() || undefined },
+          () => ({
+            kind: "evenai",
+            message: err && err.message ? err.message : String(err),
+          }),
+        );
+      });
+  }
+
   /**
    * Build, cache, and broadcast the current status.
    */
@@ -1790,10 +2719,24 @@ function createRelay(opts) {
     if (next !== null) {
       server.broadcast(next);
     }
+    if (server && typeof server.notifyAgentAvatarChanged === "function") {
+      const hash =
+        upstreamRuntime && typeof upstreamRuntime.getAgentAvatarHash === "function"
+          ? upstreamRuntime.getAgentAvatarHash()
+          : null;
+      const dataUri =
+        hash &&
+        upstreamRuntime &&
+        typeof upstreamRuntime.getAgentAvatarDataUriByHash === "function"
+          ? upstreamRuntime.getAgentAvatarDataUriByHash(hash)
+          : null;
+      server.notifyAgentAvatarChanged(hash, dataUri);
+    }
   }
 
   upstreamRuntime = createUpstreamRuntime({
     logger,
+    stateDir: opts.stateDir,
     gatewayBridge,
     conversationState,
     sessionService,
@@ -1802,6 +2745,11 @@ function createRelay(opts) {
     broadcastPages,
     broadcastStatus,
     broadcastActivity,
+    broadcastProviderUsageSnapshot,
+    operationRegistry: relayOperationRegistry,
+    getCurrentSessionModelConfigSnapshot() {
+      return currentSessionModelConfigSnapshot;
+    },
     resetActivityStatusAdapter,
     modelsCacheTtlMs: opts.modelsCacheTtlMs,
     getServer() {
@@ -1810,8 +2758,39 @@ function createRelay(opts) {
     getVoiceRuntime() {
       return null;
     },
+    gatewayUrl: opts.gatewayUrl,
+    gatewayToken: opts.gatewayToken,
+    fetchAgentAvatar: opts.fetchAgentAvatar,
   });
 
+  // Shared routing gate for session-scoped Even AI defaults (thinking seed,
+  // fast-mode patch): never touch active-routed sessions; always seed fresh
+  // background_new sessions; seed persistent background sessions only before
+  // their first turn exists.
+  async function shouldSeedSessionScopedDefaultForRoute(route) {
+    const routingMode =
+      route && typeof route.routingMode === "string"
+        ? route.routingMode.trim().toLowerCase()
+        : "active";
+    const sessionKey =
+      route && typeof route.sessionKey === "string" ? route.sessionKey.trim() : "";
+    if (!sessionKey || routingMode === "active") {
+      return false;
+    }
+    if (routingMode === "background_new") {
+      return true;
+    }
+    if (routingMode !== "background") {
+      return false;
+    }
+    try {
+      const existingSessions = await sessionService.getSessionsByExactKeys([sessionKey]);
+      return existingSessions.length === 0;
+    } catch {
+      return false;
+    }
+  }
+
   if (opts.evenAiEnabled === true) {
     evenAiRouter = createEvenAiRouter({
       sessionService,
@@ -1829,7 +2808,7 @@ function createRelay(opts) {
       logger,
       httpServer: sharedHttpServer,
       enabled: true,
-      externallyRouted: opts.evenAiExternalHttpRouting === true,
+      externallyRouted: true,
       token: opts.evenAiToken,
       getSettingsSnapshot() {
         return evenAiSettingsStore.getSnapshot();
@@ -1850,6 +2829,9 @@ function createRelay(opts) {
       emitListenInterceptRecovery(params) {
         return emitListenInterceptRecovery(params);
       },
+      emitListenInterceptBroadcast(params) {
+        return emitListenInterceptBroadcast(params);
+      },
       hasConnectedAppClient() {
         return server ? server.getConnectedAppCount() > 0 : false;
       },
@@ -1869,31 +2851,29 @@ function createRelay(opts) {
       },
       async shouldSeedThinkingForRoute(params) {
         const route = params && params.route ? params.route : params;
-        const routingMode =
-          route && typeof route.routingMode === "string"
-            ? route.routingMode.trim().toLowerCase()
-            : "active";
         const thinkingLevel =
           params && typeof params.thinkingLevel === "string"
             ? params.thinkingLevel.trim().toLowerCase()
             : "";
-        const sessionKey =
-          route && typeof route.sessionKey === "string" ? route.sessionKey.trim() : "";
-        if (!thinkingLevel || !sessionKey || routingMode === "active") {
+        if (!thinkingLevel) {
           return false;
         }
-        if (routingMode === "background_new") {
-          return true;
-        }
-        if (routingMode !== "background") {
+        return shouldSeedSessionScopedDefaultForRoute(route);
+      },
+      async seedFastModeForRoute(params) {
+        const route = params && params.route ? params.route : params;
+        const settings = evenAiSettingsStore.getSnapshot();
+        if (!settings || settings.defaultFastMode !== true) {
           return false;
         }
-        try {
-          const existingSessions = await sessionService.getSessionsByExactKeys([sessionKey]);
-          return existingSessions.length === 0;
-        } catch {
+        if (!(await shouldSeedSessionScopedDefaultForRoute(route))) {
           return false;
         }
+        const result = await sessionService.setSessionModelConfig(
+          route.sessionKey.trim(),
+          { fastMode: true },
+        );
+        return !!(result && result.status === "accepted");
       },
       onSessionActivated(route) {
         if (!route || !route.sessionChanged) {
@@ -1910,15 +2890,70 @@ function createRelay(opts) {
     });
   }
 
+  async function handleBufferedEvenAiHttpRequest(envelope) {
+    if (!evenAiEndpoint || typeof evenAiEndpoint.handleRequest !== "function") {
+      return {
+        statusCode: 404,
+        headers: { "content-type": "text/plain; charset=utf-8" },
+        body: Buffer.from("not found"),
+      };
+    }
+    const req = createBufferedHttpRequest(envelope);
+    const res = createBufferedHttpResponse(opts.evenAiMaxResponseBytes || 262_144);
+    const requestId =
+      envelope && typeof envelope.requestId === "string" ? envelope.requestId : null;
+    if (requestId) {
+      pendingBufferedEvenAiResponses.set(requestId, { req, res });
+    }
+    try {
+      await Promise.resolve(evenAiEndpoint.handleRequest(req, res));
+      if (!res.writableEnded) {
+        res.statusCode = 404;
+        res.setHeader("content-type", "text/plain; charset=utf-8");
+        res.end("not found");
+      }
+      return res.toResult();
+    } finally {
+      if (requestId) {
+        pendingBufferedEvenAiResponses.delete(requestId);
+      }
+    }
+  }
+
+  function cancelBufferedEvenAiHttpRequest(envelope) {
+    const requestId =
+      envelope && typeof envelope.requestId === "string" ? envelope.requestId : null;
+    if (!requestId) {
+      return false;
+    }
+    const pending = pendingBufferedEvenAiResponses.get(requestId);
+    if (!pending) {
+      return false;
+    }
+    pending.res.emit("close");
+    pending.req.emit("close");
+    return true;
+  }
+
   // --- Public API ---
 
-  return {
+  relayApi = {
+    /**
+     * Emit a glasses-UI surface-lifecycle event on the permanent
+     * `glasses.lifecycle` debug category (nav reconcile + cron pause/resume/
+     * tick). Recorded only when the category is enabled via debug-set. Wired
+     * through the relay-service facade into the glasses-ui tool handler + cron
+     * engine. See docs/superpowers/findings/2026-05-30-glasses-ui-phase4-hardware.md.
+     */
+    emitGlassesUiLifecycle(event, severity, data) {
+      emitDebug("glasses.lifecycle", event, severity, {}, () => data || {});
+    },
     /**
      * Start the upstream OpenClaw connection.
      * The downstream server is already listening from construction.
-     */
+    */
     start() {
-      return Promise.resolve(gatewayBridge.start()).then(() => {
+      const startGateway = () => Promise.resolve(gatewayBridge.start()).then(() => {
         prefetchSonioxModels("relay_start").catch((err) => {
           logger.warn(`[relay] Soniox models prefetch failed: ${err.message}`);
         });
@@ -1926,6 +2961,10 @@ function createRelay(opts) {
           return upstreamRuntime.start();
         }
       });
+      if (server && typeof server.start === "function") {
+        return Promise.resolve(server.start()).then(startGateway);
+      }
+      return startGateway();
     },
 
     /**
@@ -1944,10 +2983,12 @@ function createRelay(opts) {
       if (upstreamRuntime) {
         upstreamRuntime.stop();
       }
+      relayHealth.stop();
       gatewayBridge.stop();
-      return Promise.resolve(server.close()).then(() =>
-        closeOwnedRelayHttpServer(ownedHttpServer),
-      );
+      return Promise.all([
+        sessionService.flushFirstSentUserMessageCache(),
+        Promise.resolve(server.close()),
+      ]).then(() => undefined);
     },
 
     handleEvenAiHttpRequest(req, res) {
@@ -1957,11 +2998,34 @@ function createRelay(opts) {
       return Promise.resolve(evenAiEndpoint.handleRequest(req, res));
     },
 
+    handleBufferedEvenAiHttpRequest,
+
     /** The downstream server instance. */
     get server() {
       return server;
     },
 
+    get workerReadyForTest() {
+      return server && server.readyPromise ? server.readyPromise : Promise.resolve();
+    },
+
+    get debugStoreForTest() {
+      return debugStore;
+    },
+
+    get liveUiTraceLogEnabledForTest() {
+      return liveUiTraceLogEnabled;
+    },
+    __onTraceLogSetForTest(clientId, request) {
+      return applyTraceLogSet(clientId, request);
+    },
+
+    get operationRegistryForTest() {
+      return relayOperationRegistry;
+    },
+
+    relayHealth,
+
     get httpServer() {
       return sharedHttpServer;
     },
@@ -1969,7 +3033,90 @@ function createRelay(opts) {
     getEvenAiSettingsSnapshot() {
       return evenAiSettingsStore.getSnapshot();
     },
+
+    getSessionTitle(sessionKey) {
+      return sessionService.getSessionTitle(sessionKey);
+    },
+
+    hasRecordedUserMessage(sessionKey) {
+      return sessionService.hasRecordedFirstUserMessage(sessionKey);
+    },
+
+    isNeuralSessionNamesEnabled(sessionKey) {
+      return sessionService.isNeuralSessionNamesEnabled(sessionKey);
+    },
+
+    isSessionUserLocked(sessionKey) {
+      return sessionService.isSessionUserLocked(sessionKey);
+    },
+
+    peekSessionKey() {
+      return sessionService.peekSessionKey();
+    },
+
+    /**
+     * Test/shutdown hook: resolves once the async first-user-message cache
+     * write has fully drained (no write in flight, no dirty mark pending) so
+     * the on-disk file reflects the latest in-memory map.
+     */
+    flushFirstSentUserMessageCache() {
+      return sessionService.flushFirstSentUserMessageCache();
+    },
+
+    recordNeuralSessionNamesEnabled(sessionKey, enabled) {
+      sessionService.recordNeuralSessionNamesEnabled(sessionKey, enabled);
+    },
+
+    setSessionTitle(sessionKey, title, opts) {
+      const result = sessionService.setSessionTitle(sessionKey, title, opts);
+      if (result && result.ok) {
+        broadcastSessions();
+      }
+      return result;
+    },
+
+    /**
+     * Test-only: direct access to dispatchOcuClawUserSend so integration
+     * tests can drive per-turn signal plumbing without a live downstream
+     * WebSocket connection.
+     */
+    _dispatchOcuClawUserSend(params) {
+      return dispatchOcuClawUserSend(params || {});
+    },
+
+    sendGlassesUiRender(params) {
+      sendGlassesUiRender(params);
+    },
+
+    sendGlassesUiSurfaceUpdate(params) {
+      sendGlassesUiSurfaceUpdate(params);
+    },
+
+    onGlassesUiResult(handler) {
+      return onGlassesUiResult(handler);
+    },
+
+    onGlassesUiNavEvent(handler) {
+      return onGlassesUiNavEvent(handler);
+    },
+
+    sendDeviceInfoRequest(params) {
+      sendDeviceInfoRequest(params);
+    },
+
+    onDeviceInfoResponse(handler) {
+      return onDeviceInfoResponse(handler);
+    },
+
+    hasConnectedAppClient() {
+      return server ? server.getConnectedAppCount() > 0 : false;
+    },
+
+    onAppClientDisconnect(handler) {
+      return onAppClientDisconnect(handler);
+    },
   };
+  return relayApi;
 }
 
 const createRelayCore = createRelay;