ocuclaw 1.2.4 → 1.3.0

package/dist/runtime/downstream-handler.js

@@ -4,6 +4,10 @@ import {
   normalizeOcuClawDefaultThinking,
   normalizeOcuClawSystemPrompt,
 } from "./ocuclaw-settings-store.js";
+import {
+  formatMainOperationReceived,
+  formatSendAck,
+} from "./relay-worker-protocol.js";
 
 // --- Factory ---
 
@@ -27,7 +31,7 @@ function normalizeLogger(logger) {
  * downstream clients (Even App, commander.html). Consumed by relay.js.
  *
  * @param {object} opts
- * @param {(id: string, text: string, sessionKey: string|null, attachment: object|null) => Promise} opts.onSend
+ * @param {(id: string, text: string, sessionKey: string|null, attachment: object|null, clientDisplaySignals: object|null) => Promise} opts.onSend
  *   Forward a user message to the upstream OpenClaw agent.
  * @param {(sender: string, text: string) => Array} opts.onSimulate
  *   Inject a fake message into conversation state; returns pages array.
@@ -41,10 +45,14 @@ function normalizeLogger(logger) {
  *   Return cached skills catalog snapshot.
  * @param {() => Promise<{models: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetSonioxModels]
  *   Return cached Soniox model snapshot.
+ * @param {() => Promise<object>} [opts.onGetProviderUsageSnapshot]
+ *   Return the current provider usage snapshot for the active provider.
  * @param {() => Promise<object>} [opts.onGetSessionModelConfig]
  *   Return current session model controls.
  * @param {(patch: object) => Promise<{status: string, error?: string}>} [opts.onSetSessionModelConfig]
  *   Patch current session model controls.
+ * @param {({sessionKey: string}) => Promise<{status: string, error?: string}>} [opts.onCompactSession]
+ *   Trigger gateway-side compaction for a session key.
  * @param {() => Promise<object>} [opts.onGetEvenAiSettings]
  *   Return current relay-owned Even AI settings.
  * @param {() => Promise<{sessions: Array, dedicatedKey: string}>} [opts.onGetEvenAiSessions]
@@ -81,8 +89,10 @@ function createDownstreamHandler(opts) {
   const onGetModelsCatalog = opts.onGetModelsCatalog;
   const onGetSkillsCatalog = opts.onGetSkillsCatalog;
   const onGetSonioxModels = opts.onGetSonioxModels || null;
+  const onGetProviderUsageSnapshot = opts.onGetProviderUsageSnapshot || null;
   const onGetSessionModelConfig = opts.onGetSessionModelConfig;
   const onSetSessionModelConfig = opts.onSetSessionModelConfig;
+  const onCompactSession = opts.onCompactSession || null;
   const onGetEvenAiSettings = opts.onGetEvenAiSettings;
   const onGetEvenAiSessions = opts.onGetEvenAiSessions;
   const onSetEvenAiSettings = opts.onSetEvenAiSettings;
@@ -96,9 +106,21 @@ function createDownstreamHandler(opts) {
   const onDebugSet = opts.onDebugSet || null;
   const onDebugDump = opts.onDebugDump || null;
   const onEventDebug = opts.onEventDebug || null;
+  const onTraceLogSet = opts.onTraceLogSet || null;
+  const onTraceLogGet = opts.onTraceLogGet || null;
   const onRemoteControl = opts.onRemoteControl || null;
+  const onAutomationState = opts.onAutomationState || null;
   const onReadinessProbe = opts.onReadinessProbe || null;
+  const onGlassesUiResult = opts.onGlassesUiResult || null;
+  const onGlassesUiRenderInject = opts.onGlassesUiRenderInject || null;
+  const onGlassesUiNavEvent = opts.onGlassesUiNavEvent || null;
+  const onDeviceInfoResponse = opts.onDeviceInfoResponse || null;
+  const onSetUserSessionTitle = opts.onSetUserSessionTitle || null;
+  const onSetSessionPinned = opts.onSetSessionPinned || null;
+  const onDeleteSessions = opts.onDeleteSessions || null;
+  const onSearchTranscripts = opts.onSearchTranscripts || null;
   const getSnapshotRevision = opts.getSnapshotRevision || null;
+  const operationRegistry = opts.operationRegistry || null;
 
   /** Client IDs subscribed to raw protocol frame forwarding. */
   const protocolSubscribers = new Set();
@@ -115,6 +137,8 @@ function createDownstreamHandler(opts) {
   const approvalResolveCache = new Map();
   const APP_PROTOCOL = {
     activity: "ocuclaw.activity.update",
+    automationStateGet: "ocuclaw.automation.state.get",
+    automationStateSnapshot: "ocuclaw.automation.state.snapshot",
     approvalRequest: "ocuclaw.approval.request",
     approvalResolve: "ocuclaw.approval.resolve",
     approvalResolveAck: "ocuclaw.approval.resolve.ack",
@@ -137,6 +161,8 @@ function createDownstreamHandler(opts) {
     messageStreamDelta: "ocuclaw.message.stream.delta",
     modelCatalogGet: "ocuclaw.model.catalog.get",
     modelCatalogSnapshot: "ocuclaw.model.catalog.snapshot",
+    providerUsageGet: "ocuclaw.provider.usage.get",
+    providerUsageSnapshot: "ocuclaw.provider.usage.snapshot",
     skillsCatalogGet: "ocuclaw.skills.catalog.get",
     skillsCatalogSnapshot: "ocuclaw.skills.catalog.snapshot",
     pages: "ocuclaw.view.pages.snapshot",
@@ -152,16 +178,20 @@ function createDownstreamHandler(opts) {
     sessionConfigSet: "ocuclaw.session.config.set",
     sessionConfigSetAck: "ocuclaw.session.config.set.ack",
     sessionConfigSnapshot: "ocuclaw.session.config.snapshot",
+    sessionCompact: "ocuclaw.session.compact",
+    sessionCompactAck: "ocuclaw.session.compact.ack",
     sessionCreate: "ocuclaw.session.create",
     sessionList: "ocuclaw.session.list",
     sessionListResult: "ocuclaw.session.list.result",
     sessionReset: "ocuclaw.session.reset",
     sessionSwitch: "ocuclaw.session.switch",
     sessionSwitchApplied: "ocuclaw.session.switch.applied",
+    sessionTitleSet: "ocuclaw.session.title.set",
     sonioxTemporaryKey: "sonioxTemporaryKey",
     sonioxTemporaryKeyError: "sonioxTemporaryKeyError",
     status: "ocuclaw.runtime.status",
     statusGet: "ocuclaw.runtime.status.get",
+    typingUpdate: "ocuclaw.typing.update",
   };
 
   // --- Format helpers ---
@@ -222,25 +252,52 @@ function createDownstreamHandler(opts) {
     return JSON.stringify({ ...activity, type: APP_PROTOCOL.activity });
   }
 
+  /**
+   * Format a typing update message for broadcast.
+   *
+   * @param {object} update - Typing fields (state, runId, sessionKey, etc.)
+   * @returns {string} JSON string
+   */
+  function formatTyping(update) {
+    return JSON.stringify({ ...update, type: APP_PROTOCOL.typingUpdate });
+  }
+
   /**
    * Format an error message for unicast.
    *
    * @param {string} error
+   * @param {{code?: string, requestId?: string, op?: string}} [meta]
    * @returns {string} JSON string
    */
-  function formatError(error) {
-    return JSON.stringify({
+  function formatError(error, meta) {
+    const msg = {
       type: "error",
       error: error || "Unknown error",
-    });
+    };
+    if (meta && typeof meta === "object" && !Array.isArray(meta)) {
+      if (typeof meta.code === "string" && meta.code.trim()) {
+        msg.code = meta.code.trim();
+      }
+      if (typeof meta.requestId === "string" && meta.requestId.trim()) {
+        msg.requestId = meta.requestId.trim();
+      }
+      if (typeof meta.op === "string" && meta.op.trim()) {
+        msg.op = meta.op.trim();
+      }
+    }
+    return JSON.stringify(msg);
   }
 
   function isExternalDebugToolMessageType(messageType) {
     return (
       messageType === "debug-set" ||
       messageType === "debug-dump" ||
+      messageType === "trace-log-set" ||
+      messageType === "trace-log-get" ||
       messageType === "remote-control" ||
-      messageType === APP_PROTOCOL.readinessProbeRequest
+      messageType === APP_PROTOCOL.automationStateGet ||
+      messageType === APP_PROTOCOL.readinessProbeRequest ||
+      messageType === "glasses_ui_render"
     );
   }
 
@@ -253,15 +310,12 @@ function createDownstreamHandler(opts) {
    * @param {string} [errorCode] - Structured error code (for deterministic client handling)
    * @returns {string} JSON string
    */
-  function formatSendAck(id, status, error, errorCode) {
-    const msg = { type: APP_PROTOCOL.messageSendAck, requestId: id, status };
-    if (error !== undefined) {
-      msg.error = error;
-    }
-    if (errorCode !== undefined) {
-      msg.errorCode = errorCode;
-    }
-    return JSON.stringify(msg);
+  function formatSendAckCompat(id, status, error, errorCode) {
+    return formatSendAck(id, status, error, errorCode);
+  }
+
+  function formatOperationReceived(data) {
+    return formatMainOperationReceived(data);
   }
 
   /**
@@ -283,10 +337,18 @@ function createDownstreamHandler(opts) {
    * Format a streaming text message for broadcast during agent runs.
    *
    * @param {string} text - Streaming assistant text
+   * @param {Array<{start: number, end: number, emoji: string}>} [spans] - Optional emoji spans
    * @returns {string} JSON string
    */
-  function formatStreaming(text) {
-    return JSON.stringify({ type: APP_PROTOCOL.messageStreamDelta, text });
+  function formatStreaming(text, emojiSpans, paceSpans) {
+    const payload = { type: APP_PROTOCOL.messageStreamDelta, text };
+    if (Array.isArray(emojiSpans) && emojiSpans.length > 0) {
+      payload.emojiSpans = emojiSpans;
+    }
+    if (Array.isArray(paceSpans) && paceSpans.length > 0) {
+      payload.paceSpans = paceSpans;
+    }
+    return JSON.stringify(payload);
   }
 
   /**
@@ -366,6 +428,75 @@ function createDownstreamHandler(opts) {
     });
   }
 
+  /**
+   * Format a provider usage snapshot for unicast.
+   *
+   * @param {object} payload
+   * @returns {string}
+   */
+  function formatProviderUsageSnapshot(payload) {
+    const provider =
+      payload && typeof payload.provider === "string" && payload.provider.trim()
+        ? payload.provider.trim()
+        : null;
+    const windows = Array.isArray(payload && payload.windows)
+      ? payload.windows.map((window) => ({
+          key:
+            window && typeof window.key === "string" && window.key.trim()
+              ? window.key.trim()
+              : null,
+          label:
+            window && typeof window.label === "string" && window.label.trim()
+              ? window.label.trim()
+              : null,
+          usedPercent:
+            Number.isFinite(window && window.usedPercent)
+              ? window.usedPercent
+              : 0,
+          resetAtMs:
+            Number.isFinite(window && window.resetAtMs)
+              ? Math.floor(window.resetAtMs)
+              : null,
+          sortOrder:
+            Number.isFinite(window && window.sortOrder)
+              ? Math.floor(window.sortOrder)
+              : null,
+        }))
+      : [];
+    return JSON.stringify({
+      type: APP_PROTOCOL.providerUsageSnapshot,
+      sessionKey:
+        payload && typeof payload.sessionKey === "string" && payload.sessionKey.trim()
+          ? payload.sessionKey.trim()
+          : null,
+      provider,
+      displayName:
+        payload && typeof payload.displayName === "string" && payload.displayName.trim()
+          ? payload.displayName.trim()
+          : provider,
+      limitingWindowKey:
+        payload &&
+        typeof payload.limitingWindowKey === "string" &&
+        payload.limitingWindowKey.trim()
+          ? payload.limitingWindowKey.trim()
+          : null,
+      windows,
+      fetchedAtMs:
+        Number.isFinite(payload && payload.fetchedAtMs)
+          ? Math.floor(payload.fetchedAtMs)
+          : Date.now(),
+      stale: !!(payload && payload.stale),
+      poolStatus:
+        payload && (payload.poolStatus === "ready" || payload.poolStatus === "exhausted")
+          ? payload.poolStatus
+          : "unknown",
+      totalProfileCount:
+        Number.isFinite(payload && payload.totalProfileCount) && payload.totalProfileCount >= 0
+          ? Math.floor(payload.totalProfileCount)
+          : null,
+    });
+  }
+
   /**
    * Format current session model controls.
    *
@@ -394,6 +525,11 @@ function createDownstreamHandler(opts) {
         payload && typeof payload.verboseLevel === "string"
           ? payload.verboseLevel
           : "off",
+      fastMode: !!(payload && payload.fastMode === true),
+      elevatedLevel:
+        payload && typeof payload.elevatedLevel === "string"
+          ? payload.elevatedLevel
+          : "off",
     });
   }
 
@@ -417,6 +553,30 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(out);
   }
 
+  /**
+   * Format a compactSession ack message for unicast.
+   *
+   * @param {{status: string, error?: string, requestId?: string}} payload
+   * @returns {string} JSON string
+   */
+  function formatCompactSessionAck(payload) {
+    const msg = {
+      type: APP_PROTOCOL.sessionCompactAck,
+      status:
+        payload && payload.status === "accepted" ? "accepted" : "rejected",
+    };
+    if (payload && payload.requestId) {
+      msg.requestId = String(payload.requestId);
+    }
+    if (msg.status === "rejected") {
+      msg.error =
+        payload && payload.error
+          ? String(payload.error)
+          : "compact failed";
+    }
+    return JSON.stringify(msg);
+  }
+
   /**
    * Format the current relay-owned Even AI settings snapshot.
    *
@@ -444,6 +604,7 @@ function createDownstreamHandler(opts) {
           ? payload.defaultThinking
           : "",
       listenEnabled: payload && payload.listenEnabled === true,
+      defaultFastMode: !!(payload && payload.defaultFastMode === true),
     });
   }
 
@@ -491,6 +652,7 @@ function createDownstreamHandler(opts) {
           ? payload.defaultThinking
           : undefined,
       ),
+      defaultFastMode: !!(payload && payload.defaultFastMode === true),
     });
   }
 
@@ -539,23 +701,52 @@ function createDownstreamHandler(opts) {
    */
   function formatApproval(data) {
     const request = data && data.request ? data.request : {};
+    const approvalKind =
+      (data && data.approvalKind === "plugin") ||
+      (data && typeof data.id === "string" && data.id.startsWith("plugin:")) ||
+      (typeof request.title === "string" && request.title.length > 0)
+        ? "plugin"
+        : "exec";
+    const isPluginApproval = approvalKind === "plugin";
+    const commandText =
+      request.command ||
+      (request.host === "node" && request.systemRunPlan && typeof request.systemRunPlan.commandText === "string"
+        ? request.systemRunPlan.commandText
+        : "") ||
+      (isPluginApproval && typeof request.title === "string" ? request.title : "") ||
+      "";
+    const pluginDescription =
+      isPluginApproval && typeof request.description === "string" && request.description.length > 0
+        ? request.description
+        : null;
     return JSON.stringify({
       type: APP_PROTOCOL.approvalRequest,
       id: data.id,
+      ...(isPluginApproval ? { approvalKind: "plugin" } : {}),
       requestId:
         (data && typeof data.requestId === "string" && data.requestId) ||
         (request && typeof request.requestId === "string" && request.requestId) ||
         null,
-      command: request.command || "",
-      cwd: request.cwd || null,
+      command: commandText,
+      cwd: request.cwd || pluginDescription || null,
       agentId: request.agentId || null,
-      host: request.host || null,
-      security: request.security || null,
+      host: request.host || (isPluginApproval ? "plugin" : null),
+      security: request.security || (isPluginApproval && typeof request.severity === "string" ? request.severity : null),
       ask: request.ask || null,
       resolvedPath: request.resolvedPath || null,
       sessionKey: request.sessionKey || null,
+      ...(isPluginApproval
+        ? {
+            pluginId: typeof request.pluginId === "string" ? request.pluginId : null,
+            toolName: typeof request.toolName === "string" ? request.toolName : null,
+            description: pluginDescription,
+          }
+        : {}),
       createdAtMs: data.createdAtMs || 0,
       expiresAtMs: data.expiresAtMs || 0,
+      allowedDecisions: Array.isArray(request.allowedDecisions)
+        ? request.allowedDecisions.filter((d) => typeof d === "string")
+        : null,
     });
   }
 
@@ -611,17 +802,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a transcription update for broadcast during voice mode.
-   *
-   * @param {string} text - Current transcription text
-   * @param {boolean} isFinal - Whether this is a final transcription
-   * @returns {string} JSON string
-   */
-  function formatTranscription(text, isFinal) {
-    return JSON.stringify({ type: "transcription", text, final: isFinal });
-  }
-
   /**
    * Format a committed listen handoff update for broadcast during voice mode.
    *
@@ -639,6 +819,13 @@ function createDownstreamHandler(opts) {
     });
   }
 
+  function formatEvenAiListenIntercepted(sessionKey) {
+    return JSON.stringify({
+      type: "even-ai-listen-intercepted",
+      sessionKey: sessionKey ?? null,
+    });
+  }
+
   /**
    * Format a listen-ended message for broadcast.
    * @returns {string} JSON string
@@ -728,6 +915,10 @@ function createDownstreamHandler(opts) {
         : "";
     const lowered = message.toLowerCase();
     if (!message) return "soniox_temp_key_request_failed";
+    // AbortError from the per-fetch timeout AbortController in mintSonioxTemporaryKey.
+    if (err && err.name === "AbortError") {
+      return "soniox_temp_key_mint_timeout";
+    }
     if (lowered.includes("is not available")) {
       return "soniox_temp_key_unavailable";
     }
@@ -776,6 +967,27 @@ function createDownstreamHandler(opts) {
     });
   }
 
+  /**
+   * Parse a "trace-log-set" message.
+   * @returns {{enabled: boolean}}
+   */
+  function parseTraceLogSet(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("trace-log-set requires an object");
+    }
+    if (typeof msg.enabled !== "boolean") {
+      throw new Error("trace-log-set requires boolean 'enabled'");
+    }
+    return { enabled: msg.enabled };
+  }
+
+  /**
+   * Format a trace-log response for unicast (set + get share one type).
+   */
+  function formatTraceLog(data) {
+    return JSON.stringify({ type: "trace-log", ...data });
+  }
+
   /**
    * Format the current relay debug-config snapshot for app/WebUI clients.
    *
@@ -833,6 +1045,41 @@ function createDownstreamHandler(opts) {
     });
   }
 
+  function formatAutomationStateRequest(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.automationStateGet,
+      requestId:
+        data && typeof data.requestId === "string" && data.requestId
+          ? data.requestId
+          : null,
+      sessionKey:
+        data && typeof data.sessionKey === "string" && data.sessionKey
+          ? data.sessionKey
+          : null,
+    });
+  }
+
+  function formatAutomationStateSnapshot(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.automationStateSnapshot,
+      ok: data && data.ok !== false,
+      requestId:
+        data && typeof data.requestId === "string" && data.requestId
+          ? data.requestId
+          : null,
+      state:
+        data && data.state && typeof data.state === "object" ? data.state : null,
+      reasonCode:
+        data && typeof data.reasonCode === "string" && data.reasonCode
+          ? data.reasonCode
+          : null,
+      message:
+        data && typeof data.message === "string" && data.message
+          ? data.message
+          : null,
+    });
+  }
+
   function formatReadinessProbeRequest(data) {
     return JSON.stringify({
       type: APP_PROTOCOL.readinessProbeRequest,
@@ -963,25 +1210,12 @@ function createDownstreamHandler(opts) {
     ) {
       throw new Error("debug-dump untilMs must be a non-negative number");
     }
-    if (msg.redaction !== undefined) {
-      if (typeof msg.redaction !== "string") {
-        throw new Error("debug-dump redaction must be one of: safe, full");
-      }
-      const normalized = msg.redaction.trim().toLowerCase();
-      if (normalized !== "safe" && normalized !== "full") {
-        throw new Error("debug-dump redaction must be one of: safe, full");
-      }
-    }
     return {
       categories,
       limit: msg.limit === undefined ? undefined : Number(msg.limit),
       sinceMs: msg.sinceMs === undefined ? undefined : Number(msg.sinceMs),
       sinceAgeMs: msg.sinceAgeMs === undefined ? undefined : Number(msg.sinceAgeMs),
       untilMs: msg.untilMs === undefined ? undefined : Number(msg.untilMs),
-      redaction:
-        msg.redaction === undefined
-          ? undefined
-          : msg.redaction.trim().toLowerCase(),
     };
   }
 
@@ -1187,26 +1421,6 @@ 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}`);
   }
 
@@ -1320,6 +1534,20 @@ function createDownstreamHandler(opts) {
       payload.verboseLevel = normalized;
     }
 
+    const fastMode = parseOptionalBoolean(msg.fastMode, "fastMode");
+    if (fastMode !== undefined) {
+      payload.fastMode = fastMode;
+    }
+
+    const elevatedLevel = parseOptionalTrimmedString(msg.elevatedLevel);
+    if (elevatedLevel) {
+      const normalized = elevatedLevel.toLowerCase();
+      if (!["off", "on", "ask", "full"].includes(normalized)) {
+        throw new Error("elevatedLevel must be off|on|ask|full");
+      }
+      payload.elevatedLevel = normalized;
+    }
+
     if (Object.keys(payload).length === 0) {
       throw new Error("setSessionModelConfig requires at least one field");
     }
@@ -1391,6 +1619,13 @@ function createDownstreamHandler(opts) {
       payload.listenEnabled = msg.listenEnabled;
     }
 
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultFastMode")) {
+      if (typeof msg.defaultFastMode !== "boolean") {
+        throw new Error("defaultFastMode must be a boolean");
+      }
+      payload.defaultFastMode = msg.defaultFastMode;
+    }
+
     if (Object.keys(payload).length === 0) {
       throw new Error("setEvenAiSettings requires at least one field");
     }
@@ -1426,6 +1661,13 @@ function createDownstreamHandler(opts) {
       payload.defaultThinking = normalizeOcuClawDefaultThinking(msg.defaultThinking);
     }
 
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultFastMode")) {
+      if (typeof msg.defaultFastMode !== "boolean") {
+        throw new Error("defaultFastMode must be a boolean");
+      }
+      payload.defaultFastMode = msg.defaultFastMode;
+    }
+
     if (Object.keys(payload).length === 0) {
       throw new Error("setOcuClawSettings requires at least one field");
     }
@@ -1518,6 +1760,20 @@ function createDownstreamHandler(opts) {
       return payload;
     }
 
+    if (action === "setting-set") {
+      const settingKey = parseOptionalTrimmedString(msg.settingKey);
+      const value = parseOptionalTrimmedString(msg.value);
+      if (!settingKey) {
+        throw new Error("remote-control setting-set requires settingKey");
+      }
+      if (!value) {
+        throw new Error("remote-control setting-set requires value");
+      }
+      payload.settingKey = settingKey;
+      payload.value = value;
+      return payload;
+    }
+
     if (action === "relay-action") {
       payload.relayAction = normalizeRemoteRelayAction(msg.relayAction);
       if (
@@ -1598,6 +1854,20 @@ function createDownstreamHandler(opts) {
     };
   }
 
+  function parseAutomationStateGet(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("automation state payload must be an object");
+    }
+    const requestId = parseOptionalTrimmedString(msg.requestId);
+    if (!requestId) {
+      throw new Error("automation state request requires requestId");
+    }
+    return {
+      requestId,
+      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;
@@ -1736,6 +2006,32 @@ function createDownstreamHandler(opts) {
     };
   }
 
+  /**
+   * Validate and normalize an inbound clientDisplaySignals envelope.
+   * Returns null if absent or unparseable. Falls back to safe defaults
+   * for individual fields rather than rejecting the whole envelope.
+   */
+  function parseClientDisplaySignals(raw) {
+    if (raw == null || typeof raw !== "object") return null;
+    const coerceState = (val) => {
+      const s = typeof val === "string" ? val : null;
+      return s === "active" || s === "recently-disabled" || s === "inactive"
+        ? s
+        : "inactive";
+    };
+    const state = coerceState(raw.neuralEmojiReactorState);
+    const paceState = coerceState(raw.neuralPaceModulatorState);
+    const enabledRaw = raw.neuralSessionNamesEnabled;
+    const neuralSessionNamesEnabled =
+      typeof enabledRaw === "boolean" ? enabledRaw : true;
+    // readSpeedWpm tolerated but ignored on inbound for old clients.
+    return {
+      neuralEmojiReactorState: state,
+      neuralPaceModulatorState: paceState,
+      neuralSessionNamesEnabled,
+    };
+  }
+
   // --- Message handlers ---
 
   /**
@@ -1749,7 +2045,7 @@ function createDownstreamHandler(opts) {
     const requestId = parseOptionalTrimmedString(msg.requestId);
     if (!requestId) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           requestId,
           "rejected",
           "Missing required field: requestId",
@@ -1760,7 +2056,7 @@ function createDownstreamHandler(opts) {
     const parsedAttachment = parseAttachment(msg.attachment);
     if (!parsedAttachment.ok) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           requestId,
           "rejected",
           parsedAttachment.error,
@@ -1772,7 +2068,7 @@ function createDownstreamHandler(opts) {
     const text = typeof msg.text === "string" ? msg.text : "";
     if (!text.trim() && !parsedAttachment.attachment) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           requestId,
           "rejected",
           "Missing required field: text",
@@ -1783,7 +2079,7 @@ function createDownstreamHandler(opts) {
     // Check upstream connectivity
     if (!isUpstreamConnected()) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           requestId,
           "rejected",
           "OpenClaw disconnected",
@@ -1791,26 +2087,66 @@ function createDownstreamHandler(opts) {
       };
     }
 
+    const operation =
+      operationRegistry && typeof operationRegistry.beginMessageSend === "function"
+        ? operationRegistry.beginMessageSend({
+            requestId,
+            clientId,
+            sessionKey: msg.sessionKey || null,
+          })
+        : null;
+
+    if (operation && operation.duplicate) {
+      const frames = operation.finalFrame
+        ? [operation.receipt, operation.finalFrame]
+        : [operation.receipt];
+      return { unicast: frames };
+    }
+
+    const clientDisplaySignals = parseClientDisplaySignals(msg.clientDisplaySignals);
+
     // Forward to upstream — resolves on initial ack (accepted/queued)
-    return onSend(
+    const followup = onSend(
       requestId,
       text,
       msg.sessionKey || null,
       parsedAttachment.attachment,
+      clientDisplaySignals,
     ).then(
       (result) => {
         const status = (result && result.status) || "accepted";
-        return { unicast: formatSendAck(requestId, status) };
+        const frame = formatSendAckCompat(requestId, status);
+        if (operation && typeof operation.complete === "function") {
+          operation.complete(frame, { status });
+        }
+        return { unicast: frame };
       },
-      (err) => ({
-        unicast: formatSendAck(
+      (err) => {
+        const frame = formatSendAckCompat(
           requestId,
           "rejected",
           err.message || "Send failed",
-          err.errorCode || undefined,
-        ),
-      }),
+          err.errorCode || err.code || undefined,
+        );
+        if (operation && typeof operation.fail === "function") {
+          operation.fail(frame, {
+            errorCode: err.errorCode || err.code || null,
+            message: err.message || "Send failed",
+          });
+        }
+        return { unicast: frame };
+      },
     );
+
+    return operation
+      ? {
+          unicast: operation.receipt || formatOperationReceived({
+            requestId,
+            operation: "message.send",
+          }),
+          followup,
+        }
+      : followup;
   }
 
   /**
@@ -1839,7 +2175,7 @@ function createDownstreamHandler(opts) {
     const id = parseOptionalTrimmedString(msg.id);
     if (!id) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           msg.id || null,
           "rejected",
           "Missing required field: id",
@@ -1849,7 +2185,7 @@ function createDownstreamHandler(opts) {
 
     if (!onSimulateStream) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           id,
           "rejected",
           "simulateStream not supported by relay",
@@ -1860,7 +2196,7 @@ function createDownstreamHandler(opts) {
     const text = typeof msg.text === "string" ? msg.text : "";
     if (!text.trim()) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           id,
           "rejected",
           "simulateStream requires non-empty text",
@@ -1879,7 +2215,7 @@ function createDownstreamHandler(opts) {
       thinkingTailMs = parseOptionalNonNegativeNumber(msg.thinkingTailMs, "thinkingTailMs");
     } catch (err) {
       return {
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           id,
           "rejected",
           err && err.message ? err.message : "Invalid simulateStream parameters",
@@ -1902,10 +2238,10 @@ function createDownstreamHandler(opts) {
       (result) => {
         const status = result && result.status ? result.status : "accepted";
         const error = result && result.error ? result.error : undefined;
-        return { unicast: formatSendAck(id, status, error) };
+        return { unicast: formatSendAckCompat(id, status, error) };
       },
       (err) => ({
-        unicast: formatSendAck(
+        unicast: formatSendAckCompat(
           id,
           "rejected",
           err && err.message ? err.message : "simulateStream failed",
@@ -2168,6 +2504,41 @@ function createDownstreamHandler(opts) {
     );
   }
 
+  /**
+   * Handle "getProviderUsageSnapshot": return the current provider usage snapshot.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetProviderUsageSnapshot(clientId) {
+    const emptySnapshot = () => ({
+      sessionKey: null,
+      provider: null,
+      displayName: null,
+      limitingWindowKey: null,
+      windows: [],
+      fetchedAtMs: Date.now(),
+      stale: true,
+    });
+
+    if (!onGetProviderUsageSnapshot) {
+      return {
+        unicast: formatProviderUsageSnapshot(emptySnapshot()),
+      };
+    }
+    return Promise.resolve(onGetProviderUsageSnapshot()).then(
+      (payload) => ({
+        unicast: formatProviderUsageSnapshot(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getProviderUsageSnapshot failed: ${err.message}`);
+        return {
+          unicast: formatProviderUsageSnapshot(emptySnapshot()),
+        };
+      },
+    );
+  }
+
   /**
    * Handle "getStatus": return the current status snapshot.
    *
@@ -2252,6 +2623,53 @@ function createDownstreamHandler(opts) {
     );
   }
 
+  /**
+   * Handle "compactSession": trigger gateway-side compaction for a session key.
+   *
+   * @param {string} clientId
+   * @param {object} msg - { sessionKey, requestId }
+   * @returns {Promise<{ unicast: string }>}
+   */
+  function handleCompactSession(clientId, msg) {
+    if (!onCompactSession) {
+      return Promise.resolve({
+        unicast: formatCompactSessionAck({
+          status: "rejected",
+          requestId: msg && msg.requestId,
+          error: "compactSession is not available",
+        }),
+      });
+    }
+    const sessionKey =
+      msg && typeof msg.sessionKey === "string" && msg.sessionKey
+        ? msg.sessionKey
+        : null;
+    if (!sessionKey) {
+      return Promise.resolve({
+        unicast: formatCompactSessionAck({
+          status: "rejected",
+          requestId: msg && msg.requestId,
+          error: "sessionKey is required",
+        }),
+      });
+    }
+    return Promise.resolve(onCompactSession({ sessionKey })).then(
+      (result) => ({
+        unicast: formatCompactSessionAck({
+          ...(result || { status: "accepted" }),
+          requestId: msg.requestId,
+        }),
+      }),
+      (err) => ({
+        unicast: formatCompactSessionAck({
+          status: "rejected",
+          requestId: msg.requestId,
+          error: err && err.message ? err.message : "compactSession failed",
+        }),
+      }),
+    );
+  }
+
   /**
    * Handle "getEvenAiSettings": read relay-owned Even AI settings.
    *
@@ -2447,6 +2865,65 @@ function createDownstreamHandler(opts) {
     );
   }
 
+  /**
+   * Handle a "session.title.set" message: user-edited session title from
+   * phone UI. Sticky-locks the agent against retitling.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with sessionKey and title
+   * @returns {null}
+   */
+  function handleSetUserSessionTitle(clientId, msg) {
+    if (typeof onSetUserSessionTitle !== "function") return null;
+    const sessionKey =
+      typeof msg.sessionKey === "string" ? msg.sessionKey.trim() : "";
+    const title = typeof msg.title === "string" ? msg.title.trim() : "";
+    if (!sessionKey || !title) return null;
+    if (title.length > 55) return null;
+    onSetUserSessionTitle(sessionKey, title);
+    return null;
+  }
+
+  function handleSetSessionPinned(clientId, msg) {
+    if (typeof onSetSessionPinned !== "function") return null;
+    const sessionKey =
+      typeof msg.sessionKey === "string" ? msg.sessionKey.trim() : "";
+    const pinned = msg.pinned === true;
+    const kind = msg.kind;
+    if (!sessionKey || (kind !== "ocuclaw" && kind !== "evenai")) {
+      return { unicast: formatError("invalid_session_pin_request") };
+    }
+    const result = onSetSessionPinned(sessionKey, pinned, kind);
+    if (result && result.ok === false) {
+      const code = result.reason === "cap" ? "pin_cap_reached" : "invalid_session_pin_request";
+      return { unicast: formatError(code) };
+    }
+    return null;
+  }
+
+  function handleDeleteSessions(clientId, msg) {
+    if (typeof onDeleteSessions !== "function") return null;
+    const sessionKeys = Array.isArray(msg.sessionKeys) ? msg.sessionKeys.filter((k) => typeof k === "string" && k) : [];
+    const kind = msg.kind;
+    const switchBeforeDelete = msg.switchBeforeDelete === true;
+    if (sessionKeys.length === 0 || (kind !== "ocuclaw" && kind !== "evenai")) {
+      return { unicast: formatError("invalid_session_delete_request") };
+    }
+    onDeleteSessions(sessionKeys, kind, switchBeforeDelete);
+    return null;
+  }
+
+  function handleSearchTranscripts(clientId, msg) {
+    if (typeof onSearchTranscripts !== "function") return null;
+    const query = typeof msg.query === "string" ? msg.query : "";
+    const kind = msg.kind;
+    if (!query.trim() || (kind !== "ocuclaw" && kind !== "evenai")) {
+      return { unicast: formatError("invalid_transcript_search_request") };
+    }
+    onSearchTranscripts(clientId, query, kind);
+    return null;
+  }
+
   /**
    * Handle a "slashCommand" message: forward a slash command to OpenClaw.
    *
@@ -2650,6 +3127,36 @@ function createDownstreamHandler(opts) {
     }
   }
 
+  function handleTraceLogSet(clientId, msg) {
+    if (!onTraceLogSet) {
+      return { unicast: formatError("trace-log-set is not available") };
+    }
+    let payload;
+    try {
+      payload = parseTraceLogSet(msg);
+    } catch (err) {
+      return { unicast: formatError(err.message) };
+    }
+    try {
+      const result = onTraceLogSet(clientId, payload) || { ok: true };
+      return { unicast: formatTraceLog(result) };
+    } catch (err) {
+      return { unicast: formatError(err.message || "trace-log-set failed") };
+    }
+  }
+
+  function handleTraceLogGet(clientId) {
+    if (!onTraceLogGet) {
+      return { unicast: formatError("trace-log-get is not available") };
+    }
+    try {
+      const result = onTraceLogGet(clientId) || { ok: true };
+      return { unicast: formatTraceLog(result) };
+    } catch (err) {
+      return { unicast: formatError(err.message || "trace-log-get failed") };
+    }
+  }
+
   /**
    * Handle a "remote-control" message: dispatch remote actions to app clients.
    */
@@ -2757,6 +3264,82 @@ function createDownstreamHandler(opts) {
     }
   }
 
+  function handleAutomationState(clientId, msg) {
+    let payload;
+    try {
+      payload = parseAutomationStateGet(msg);
+    } catch (err) {
+      return {
+        unicast: formatAutomationStateSnapshot({
+          ok: false,
+          requestId:
+            msg && typeof msg.requestId === "string" ? msg.requestId : null,
+          reasonCode: "snapshot_unavailable",
+          message: err.message,
+        }),
+      };
+    }
+
+    if (!onAutomationState) {
+      return null;
+    }
+
+    const finalize = (result) => {
+      const resolved = result || {};
+      const requestId = resolved.requestId || payload.requestId;
+      if (
+        resolved.ok === false ||
+        !resolved.targetClientId ||
+        !resolved.request
+      ) {
+        return {
+          unicast: formatAutomationStateSnapshot({
+            ok: false,
+            requestId,
+            reasonCode: resolved.reasonCode || "snapshot_unavailable",
+            message:
+              resolved.message || "automation state request was not dispatched",
+          }),
+        };
+      }
+
+      return {
+        automationStateRequest: {
+          requestId,
+          targetClientId: resolved.targetClientId,
+          message: formatAutomationStateRequest(resolved.request),
+        },
+      };
+    };
+
+    try {
+      const result = onAutomationState(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => finalize(resolved),
+          (err) => ({
+            unicast: formatAutomationStateSnapshot({
+              ok: false,
+              requestId: payload.requestId,
+              reasonCode: "snapshot_unavailable",
+              message: err.message || "automation state request failed",
+            }),
+          }),
+        );
+      }
+      return finalize(result);
+    } catch (err) {
+      return {
+        unicast: formatAutomationStateSnapshot({
+          ok: false,
+          requestId: payload.requestId,
+          reasonCode: "snapshot_unavailable",
+          message: err.message || "automation state request failed",
+        }),
+      };
+    }
+  }
+
   // --- Public API ---
 
   return {
@@ -2805,6 +3388,14 @@ function createDownstreamHandler(opts) {
           return handleSwitchSession(clientId, msg);
         case APP_PROTOCOL.sessionCreate:
           return handleNewSession(clientId);
+        case APP_PROTOCOL.sessionTitleSet:
+          return handleSetUserSessionTitle(clientId, msg);
+        case "ocuclaw.session.pinned.set":
+          return handleSetSessionPinned(clientId, msg);
+        case "ocuclaw.session.delete":
+          return handleDeleteSessions(clientId, msg);
+        case "ocuclaw.session.transcripts.search":
+          return handleSearchTranscripts(clientId, msg);
         case APP_PROTOCOL.modelCatalogGet:
           return handleGetModelsCatalog(clientId);
         case APP_PROTOCOL.skillsCatalogGet:
@@ -2813,6 +3404,9 @@ function createDownstreamHandler(opts) {
         case APP_PROTOCOL.sonioxModelsGet:
         case "getSonioxModels":
           return handleGetSonioxModels(clientId);
+        case APP_PROTOCOL.providerUsageGet:
+        case "getProviderUsageSnapshot":
+          return handleGetProviderUsageSnapshot(clientId);
         case APP_PROTOCOL.statusGet:
         case "getStatus":
           return handleGetStatus(clientId);
@@ -2820,6 +3414,8 @@ function createDownstreamHandler(opts) {
           return handleGetSessionModelConfig(clientId);
         case APP_PROTOCOL.sessionConfigSet:
           return handleSetSessionModelConfig(clientId, msg);
+        case APP_PROTOCOL.sessionCompact:
+          return handleCompactSession(clientId, msg);
         case APP_PROTOCOL.evenAiSettingsGet:
           return handleGetEvenAiSettings(clientId);
         case APP_PROTOCOL.evenAiSessionList:
@@ -2845,12 +3441,83 @@ function createDownstreamHandler(opts) {
           return handleDebugSet(clientId, msg);
         case "debug-dump":
           return handleDebugDump(clientId, msg);
+        case "trace-log-set":
+          return handleTraceLogSet(clientId, msg);
+        case "trace-log-get":
+          return handleTraceLogGet(clientId);
         case "remote-control":
           return handleRemoteControl(clientId, msg);
+        case APP_PROTOCOL.automationStateGet:
+          return handleAutomationState(clientId, msg);
         case APP_PROTOCOL.readinessProbeRequest:
           return handleReadinessProbe(clientId, msg);
         case APP_PROTOCOL.debugEvent:
           return handleEventDebug(clientId, msg);
+        case "glasses_ui_result":
+          if (typeof onGlassesUiResult === "function") {
+            try {
+              onGlassesUiResult({
+                surfaceId: typeof msg.surfaceId === "string" ? msg.surfaceId : "",
+                outcome: msg.outcome,
+              });
+            } catch (err) {
+              logger.warn(
+                `[downstream] glasses_ui_result handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
+        case "glasses_ui_nav_event":
+          // Client-reported nav-stack transition (push reports the PARENT
+          // surfaceId; pop reports the post-pop depth) so the plugin can
+          // pause/resume the right surface's cron. Not a debug tool — stays out
+          // of isExternalDebugToolMessageType.
+          if (typeof onGlassesUiNavEvent === "function") {
+            try {
+              onGlassesUiNavEvent({
+                surfaceId: typeof msg.surfaceId === "string" ? msg.surfaceId : "",
+                depth: Number.isFinite(msg.depth) ? Math.max(1, Math.floor(msg.depth)) : 1,
+              });
+            } catch (err) {
+              logger.warn(
+                `[downstream] glasses_ui_nav_event handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
+        case "glasses_ui_render":
+          // Debug inject path used by tools/debugctl.js glasses-ui render to
+          // exercise the simulator paint loop without spinning up an agent.
+          if (typeof onGlassesUiRenderInject === "function") {
+            try {
+              onGlassesUiRenderInject({
+                surfaceId: typeof msg.surfaceId === "string" ? msg.surfaceId : "",
+                depth: Number.isFinite(msg.depth) ? Math.max(1, Math.floor(msg.depth)) : 1,
+                spec: msg.spec,
+              });
+            } catch (err) {
+              logger.warn(
+                `[downstream] glasses_ui_render inject handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
+        case "device_info_response":
+          if (typeof onDeviceInfoResponse === "function") {
+            try {
+              onDeviceInfoResponse({
+                requestId: typeof msg.requestId === "string" ? msg.requestId : "",
+                ok: msg.ok === true,
+                code: typeof msg.code === "string" ? msg.code : undefined,
+                data: msg.data && typeof msg.data === "object" ? msg.data : undefined,
+              });
+            } catch (err) {
+              logger.warn(
+                `[downstream] device_info_response handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
         default:
           return null;
       }
@@ -2859,7 +3526,8 @@ function createDownstreamHandler(opts) {
     formatPages,
     formatStatus,
     formatActivity,
-    formatSendAck,
+    formatTyping,
+    formatSendAck: formatSendAckCompat,
     formatProtocol,
     formatStreaming,
     formatSessions,
@@ -2867,6 +3535,7 @@ function createDownstreamHandler(opts) {
     formatModelsCatalog,
     formatSkillsCatalog,
     formatSonioxModels,
+    formatProviderUsageSnapshot,
     formatSessionModelConfig,
     formatSessionModelConfigAck,
     formatEvenAiSettings,
@@ -2877,8 +3546,8 @@ function createDownstreamHandler(opts) {
     formatApproval,
     formatApprovalResolved,
     formatApprovalResponseAck,
-    formatTranscription,
     formatListenCommitted,
+    formatEvenAiListenIntercepted,
     formatListenEnded,
     formatListenError,
     formatListenReady,
@@ -2889,6 +3558,8 @@ function createDownstreamHandler(opts) {
     formatDebugConfigSnapshot,
     formatRemoteControl,
     formatRemoteControlAck,
+    formatAutomationStateRequest,
+    formatAutomationStateSnapshot,
     formatReadinessProbeRequest,
     formatReadinessProbeAck,
     formatError,