ocuclaw 0.1.0

package/dist/runtime/downstream-handler.js

@@ -0,0 +1,2747 @@
+import { normalizeEvenAiRoutingMode } from "../even-ai/even-ai-settings-store.js";
+import {
+  normalizeOcuClawDefaultModel,
+  normalizeOcuClawDefaultThinking,
+  normalizeOcuClawSystemPrompt,
+} from "./ocuclaw-settings-store.js";
+
+// --- Factory ---
+
+function normalizeLogger(logger) {
+  if (!logger || typeof logger !== "object") {
+    return console;
+  }
+  return {
+    info: typeof logger.info === "function" ? logger.info.bind(logger) : console.log,
+    warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn,
+    error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error,
+    debug:
+      typeof logger.debug === "function" ? logger.debug.bind(logger) : console.debug,
+  };
+}
+
+/**
+ * Create a downstream message handler.
+ *
+ * Transport-agnostic protocol logic for processing messages from
+ * 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
+ *   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.
+   * @param {(request: object) => Promise<object>|object} [opts.onSimulateStream]
+   *   Inject deterministic streaming payload (relay-local), then finalize pages.
+ * @param {() => Promise<Array>} opts.onNewChat
+ *   Clear conversation and reset the OpenClaw session; returns empty pages array.
+ * @param {() => Promise<{models: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetModelsCatalog]
+ *   Return cached model catalog snapshot.
+ * @param {() => Promise<{skills: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetSkillsCatalog]
+ *   Return cached skills catalog snapshot.
+ * @param {() => Promise<{models: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetSonioxModels]
+ *   Return cached Soniox model snapshot.
+ * @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 {() => Promise<object>} [opts.onGetEvenAiSettings]
+ *   Return current relay-owned Even AI settings.
+ * @param {() => Promise<{sessions: Array, dedicatedKey: string}>} [opts.onGetEvenAiSessions]
+ *   Return the Even AI session-browser payload.
+ * @param {(patch: object) => Promise<{status: string, error?: string, settings?: object}>} [opts.onSetEvenAiSettings]
+ *   Patch relay-owned Even AI settings.
+ * @param {() => Promise<object>} [opts.onGetOcuClawSettings]
+ *   Return current relay-owned OcuClaw settings.
+ * @param {(patch: object) => Promise<{status: string, error?: string, settings?: object}>} [opts.onSetOcuClawSettings]
+ *   Patch relay-owned OcuClaw settings.
+ * @param {(clientId: string, payload: object) => Promise<object>|object} [opts.onRequestSonioxTemporaryKey]
+ *   Mint a short-lived Soniox temporary key for the provided voiceSessionId.
+ * @param {() => object} [opts.onGetStatus]
+ *   Return the current relay status snapshot.
+ * @param {() => boolean} opts.isUpstreamConnected
+ *   Returns true if the OpenClaw gateway connection is active.
+ * @param {(clientId: string, payload: object) => void} [opts.onEventDebug]
+ *   Optional structured client debug-event callback.
+ * @returns {object} Handler instance
+ */
+function createDownstreamHandler(opts) {
+  const logger = normalizeLogger(opts.logger);
+  const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
+  const onSend = opts.onSend;
+  const onSimulate = opts.onSimulate;
+  const onSimulateStream = opts.onSimulateStream || null;
+  const onNewChat = opts.onNewChat;
+  const onGetSessions = opts.onGetSessions;
+  const onSwitchSession = opts.onSwitchSession;
+  const onNewSession = opts.onNewSession;
+  const onSlashCommand = opts.onSlashCommand;
+  const onGetModelsCatalog = opts.onGetModelsCatalog;
+  const onGetSkillsCatalog = opts.onGetSkillsCatalog;
+  const onGetSonioxModels = opts.onGetSonioxModels || null;
+  const onGetSessionModelConfig = opts.onGetSessionModelConfig;
+  const onSetSessionModelConfig = opts.onSetSessionModelConfig;
+  const onGetEvenAiSettings = opts.onGetEvenAiSettings;
+  const onGetEvenAiSessions = opts.onGetEvenAiSessions;
+  const onSetEvenAiSettings = opts.onSetEvenAiSettings;
+  const onGetOcuClawSettings = opts.onGetOcuClawSettings;
+  const onSetOcuClawSettings = opts.onSetOcuClawSettings;
+  const onRequestSonioxTemporaryKey = opts.onRequestSonioxTemporaryKey || null;
+  const onGetStatus = opts.onGetStatus || null;
+  const isUpstreamConnected = opts.isUpstreamConnected;
+  const onConsoleLog = opts.onConsoleLog || null;
+  const onApprovalResolve = opts.onApprovalResolve || null;
+  const onDebugSet = opts.onDebugSet || null;
+  const onDebugDump = opts.onDebugDump || null;
+  const onEventDebug = opts.onEventDebug || null;
+  const onRemoteControl = opts.onRemoteControl || null;
+  const getSnapshotRevision = opts.getSnapshotRevision || null;
+
+  /** Client IDs subscribed to raw protocol frame forwarding. */
+  const protocolSubscribers = new Set();
+  const APPROVAL_DECISIONS = new Set(["allow-once", "allow-always", "deny"]);
+  const approvalResolveCacheTtlMs = Number.isFinite(opts.approvalResolveCacheTtlMs)
+    ? Math.max(1_000, Math.floor(opts.approvalResolveCacheTtlMs))
+    : 30_000;
+  const approvalResolveCacheMaxEntries = Number.isFinite(opts.approvalResolveCacheMaxEntries)
+    ? Math.max(10, Math.floor(opts.approvalResolveCacheMaxEntries))
+    : 500;
+  const EXTERNAL_DEBUG_TOOLS_DISABLED_ERROR =
+    "external debug tools are disabled by plugin config";
+  /** @type {Map<string, {expiresAtMs: number, promise: Promise<object>}>} */
+  const approvalResolveCache = new Map();
+  const APP_PROTOCOL = {
+    activity: "ocuclaw.activity.update",
+    approvalRequest: "ocuclaw.approval.request",
+    approvalResolve: "ocuclaw.approval.resolve",
+    approvalResolveAck: "ocuclaw.approval.resolve.ack",
+    approvalResolved: "ocuclaw.approval.resolved",
+    commandSlash: "ocuclaw.command.slash",
+    debugConfigSnapshot: "ocuclaw.debug.config.snapshot",
+    debugEvent: "ocuclaw.debug.event",
+    evenAiSettingsGet: "ocuclaw.evenai.settings.get",
+    evenAiSessionList: "ocuclaw.evenai.session.list",
+    evenAiSessionListResult: "ocuclaw.evenai.session.list.result",
+    evenAiSettingsSet: "ocuclaw.evenai.settings.set",
+    evenAiSettingsSetAck: "ocuclaw.evenai.settings.set.ack",
+    evenAiSettingsSnapshot: "ocuclaw.evenai.settings.snapshot",
+    ocuClawSettingsGet: "ocuclaw.settings.get",
+    ocuClawSettingsSet: "ocuclaw.settings.set",
+    ocuClawSettingsSetAck: "ocuclaw.settings.set.ack",
+    ocuClawSettingsSnapshot: "ocuclaw.settings.snapshot",
+    messageSend: "ocuclaw.message.send",
+    messageSendAck: "ocuclaw.message.send.ack",
+    messageStreamDelta: "ocuclaw.message.stream.delta",
+    modelCatalogGet: "ocuclaw.model.catalog.get",
+    modelCatalogSnapshot: "ocuclaw.model.catalog.snapshot",
+    skillsCatalogGet: "ocuclaw.skills.catalog.get",
+    skillsCatalogSnapshot: "ocuclaw.skills.catalog.snapshot",
+    pages: "ocuclaw.view.pages.snapshot",
+    protocolSubscribe: "ocuclaw.protocol.tap.subscribe",
+    protocolFrame: "ocuclaw.protocol.tap.frame",
+    remoteControl: "ocuclaw.remote.control",
+    requestSonioxTemporaryKey: "requestSonioxTemporaryKey",
+    sonioxModelsGet: "ocuclaw.voice.soniox.models.get",
+    sonioxModelsSnapshot: "ocuclaw.voice.soniox.models.snapshot",
+    sessionConfigGet: "ocuclaw.session.config.get",
+    sessionConfigSet: "ocuclaw.session.config.set",
+    sessionConfigSetAck: "ocuclaw.session.config.set.ack",
+    sessionConfigSnapshot: "ocuclaw.session.config.snapshot",
+    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",
+    sonioxTemporaryKey: "sonioxTemporaryKey",
+    sonioxTemporaryKeyError: "sonioxTemporaryKeyError",
+    status: "ocuclaw.runtime.status",
+    statusGet: "ocuclaw.runtime.status.get",
+  };
+
+  // --- Format helpers ---
+
+  /**
+   * Format a pages message for broadcast.
+   *
+   * @param {Array<{content: string, subPage: [number,number]|null}>} pages
+   * @param {{revision?: number}} [meta]
+   * @returns {string} JSON string
+   */
+  function formatPages(pages, meta) {
+    const msg = { type: APP_PROTOCOL.pages, pages };
+    const fallbackRevision = getSnapshotRevision
+      ? getSnapshotRevision("pages")
+      : null;
+    const revision = Number.isFinite(meta && meta.revision)
+      ? Math.floor(meta.revision)
+      : Number.isFinite(fallbackRevision)
+        ? Math.floor(fallbackRevision)
+        : null;
+    if (revision !== null) {
+      msg.revision = revision;
+    }
+    return JSON.stringify(msg);
+  }
+
+  /**
+   * Format a status message for broadcast.
+   *
+   * @param {object} status - Status fields (openclaw, agent, session, etc.)
+   * @param {{revision?: number}} [meta]
+   * @returns {string} JSON string
+   */
+  function formatStatus(status, meta) {
+    const msg = { ...status, type: APP_PROTOCOL.status };
+    const fallbackRevision = getSnapshotRevision
+      ? getSnapshotRevision("status")
+      : null;
+    const revision = Number.isFinite(meta && meta.revision)
+      ? Math.floor(meta.revision)
+      : Number.isFinite(fallbackRevision)
+        ? Math.floor(fallbackRevision)
+        : null;
+    if (revision !== null) {
+      msg.revision = revision;
+    }
+    return JSON.stringify(msg);
+  }
+
+  /**
+   * Format an activity message for broadcast.
+   *
+   * @param {object} activity - Activity fields (state, tool, etc.)
+   * @returns {string} JSON string
+   */
+  function formatActivity(activity) {
+    return JSON.stringify({ ...activity, type: APP_PROTOCOL.activity });
+  }
+
+  /**
+   * Format an error message for unicast.
+   *
+   * @param {string} error
+   * @returns {string} JSON string
+   */
+  function formatError(error) {
+    return JSON.stringify({
+      type: "error",
+      error: error || "Unknown error",
+    });
+  }
+
+  function isExternalDebugToolMessageType(messageType) {
+    return (
+      messageType === "debug-set" ||
+      messageType === "debug-dump" ||
+      messageType === "remote-control"
+    );
+  }
+
+  /**
+   * Format a send acknowledgement for unicast.
+   *
+   * @param {string} id - Message ID being acknowledged
+   * @param {string} status - "accepted" or "rejected"
+   * @param {string} [error] - Error message (for rejected)
+   * @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);
+  }
+
+  /**
+   * Format a protocol frame for forwarding to subscribers.
+   *
+   * @param {string} direction - "in" or "out"
+   * @param {object} frame - Raw protocol frame
+   * @returns {string} JSON string
+   */
+  function formatProtocol(direction, frame) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.protocolFrame,
+      direction,
+      frame,
+    });
+  }
+
+  /**
+   * Format a streaming text message for broadcast during agent runs.
+   *
+   * @param {string} text - Streaming assistant text
+   * @returns {string} JSON string
+   */
+  function formatStreaming(text) {
+    return JSON.stringify({ type: APP_PROTOCOL.messageStreamDelta, text });
+  }
+
+  /**
+   * Format a sessions list message for unicast response.
+   *
+   * @param {Array<{key: string, updatedAt: number, preview: string, firstUserMessage?: string}>} sessions
+   * @returns {string} JSON string
+   */
+  function formatSessions(sessions) {
+    return JSON.stringify({ type: APP_PROTOCOL.sessionListResult, sessions });
+  }
+
+  /**
+   * Format a session-switched confirmation for broadcast.
+   *
+   * @param {string} sessionKey
+   * @returns {string} JSON string
+   */
+  function formatSessionSwitched(sessionKey) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.sessionSwitchApplied,
+      sessionKey,
+    });
+  }
+
+  /**
+   * Format a model catalog snapshot for unicast.
+   *
+   * @param {{models: Array, fetchedAtMs: number, stale: boolean}} payload
+   * @returns {string}
+   */
+  function formatModelsCatalog(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.modelCatalogSnapshot,
+      models: Array.isArray(payload && payload.models) ? payload.models : [],
+      fetchedAtMs:
+        Number.isFinite(payload && payload.fetchedAtMs)
+          ? Math.floor(payload.fetchedAtMs)
+          : 0,
+      stale: !!(payload && payload.stale),
+    });
+  }
+
+  /**
+   * Format a cached skills catalog snapshot for unicast.
+   *
+   * @param {{skills?: Array, fetchedAtMs?: number, stale?: boolean}} payload
+   * @returns {string}
+   */
+  function formatSkillsCatalog(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.skillsCatalogSnapshot,
+      skills: Array.isArray(payload && payload.skills) ? payload.skills : [],
+      fetchedAtMs:
+        Number.isFinite(payload && payload.fetchedAtMs)
+          ? Math.floor(payload.fetchedAtMs)
+          : Date.now(),
+      stale: !!(payload && payload.stale),
+    });
+  }
+
+  /**
+   * Format a Soniox model snapshot for unicast.
+   *
+   * @param {{models: Array, fetchedAtMs: number, stale: boolean}} payload
+   * @returns {string}
+   */
+  function formatSonioxModels(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.sonioxModelsSnapshot,
+      models: Array.isArray(payload && payload.models) ? payload.models : [],
+      fetchedAtMs:
+        Number.isFinite(payload && payload.fetchedAtMs)
+          ? Math.floor(payload.fetchedAtMs)
+          : 0,
+      stale: !!(payload && payload.stale),
+    });
+  }
+
+  /**
+   * Format current session model controls.
+   *
+   * @param {object} payload
+   * @returns {string}
+   */
+  function formatSessionModelConfig(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.sessionConfigSnapshot,
+      sessionKey: (payload && payload.sessionKey) || "",
+      modelProvider:
+        payload && typeof payload.modelProvider === "string"
+          ? payload.modelProvider
+          : null,
+      model:
+        payload && typeof payload.model === "string" ? payload.model : null,
+      thinkingLevel:
+        payload && typeof payload.thinkingLevel === "string"
+          ? payload.thinkingLevel
+          : "",
+      reasoningLevel:
+        payload && typeof payload.reasoningLevel === "string"
+          ? payload.reasoningLevel
+          : "off",
+      verboseLevel:
+        payload && typeof payload.verboseLevel === "string"
+          ? payload.verboseLevel
+          : "off",
+    });
+  }
+
+  /**
+   * Format a session model config write acknowledgement.
+   *
+   * @param {{status: string, error?: string}} payload
+   * @returns {string}
+   */
+  function formatSessionModelConfigAck(payload) {
+    const out = {
+      type: APP_PROTOCOL.sessionConfigSetAck,
+      status:
+        payload && typeof payload.status === "string"
+          ? payload.status
+          : "rejected",
+    };
+    if (payload && payload.error !== undefined) {
+      out.error = payload.error;
+    }
+    return JSON.stringify(out);
+  }
+
+  /**
+   * Format the current relay-owned Even AI settings snapshot.
+   *
+   * @param {object} payload
+   * @returns {string}
+   */
+  function formatEvenAiSettings(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.evenAiSettingsSnapshot,
+      routingMode: normalizeEvenAiRoutingMode(
+        payload && typeof payload.routingMode === "string"
+          ? payload.routingMode
+          : undefined,
+      ),
+      systemPrompt:
+        payload && typeof payload.systemPrompt === "string"
+          ? payload.systemPrompt
+          : "",
+      defaultModel:
+        payload && typeof payload.defaultModel === "string"
+          ? payload.defaultModel
+          : "",
+      defaultThinking:
+        payload && typeof payload.defaultThinking === "string"
+          ? payload.defaultThinking
+          : "",
+      listenEnabled: payload && payload.listenEnabled === true,
+    });
+  }
+
+  /**
+   * Format an Even AI settings write acknowledgement.
+   *
+   * @param {{status: string, error?: string}} payload
+   * @returns {string}
+   */
+  function formatEvenAiSettingsAck(payload) {
+    const out = {
+      type: APP_PROTOCOL.evenAiSettingsSetAck,
+      status:
+        payload && typeof payload.status === "string"
+          ? payload.status
+          : "rejected",
+    };
+    if (payload && payload.error !== undefined) {
+      out.error = payload.error;
+    }
+    return JSON.stringify(out);
+  }
+
+  /**
+   * Format the current relay-owned OcuClaw settings snapshot.
+   *
+   * @param {object} payload
+   * @returns {string}
+   */
+  function formatOcuClawSettings(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.ocuClawSettingsSnapshot,
+      systemPrompt: normalizeOcuClawSystemPrompt(
+        payload && typeof payload.systemPrompt === "string"
+          ? payload.systemPrompt
+          : undefined,
+      ),
+      defaultModel: normalizeOcuClawDefaultModel(
+        payload && typeof payload.defaultModel === "string"
+          ? payload.defaultModel
+          : undefined,
+      ),
+      defaultThinking: normalizeOcuClawDefaultThinking(
+        payload && typeof payload.defaultThinking === "string"
+          ? payload.defaultThinking
+          : undefined,
+      ),
+    });
+  }
+
+  /**
+   * Format an OcuClaw settings write acknowledgement.
+   *
+   * @param {{status: string, error?: string}} payload
+   * @returns {string}
+   */
+  function formatOcuClawSettingsAck(payload) {
+    const out = {
+      type: APP_PROTOCOL.ocuClawSettingsSetAck,
+      status:
+        payload && typeof payload.status === "string"
+          ? payload.status
+          : "rejected",
+    };
+    if (payload && payload.error !== undefined) {
+      out.error = payload.error;
+    }
+    return JSON.stringify(out);
+  }
+
+  /**
+   * Format the Even AI session-browser result payload.
+   *
+   * @param {{sessions?: Array, dedicatedKey?: string}} payload
+   * @returns {string}
+   */
+  function formatEvenAiSessions(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.evenAiSessionListResult,
+      sessions: Array.isArray(payload && payload.sessions) ? payload.sessions : [],
+      dedicatedKey:
+        payload && typeof payload.dedicatedKey === "string"
+          ? payload.dedicatedKey
+          : "ocuclaw:even-ai",
+    });
+  }
+
+  /**
+   * Format an exec approval request for broadcast.
+   *
+   * @param {object} data - Approval payload from gateway
+   * @returns {string} JSON string
+   */
+  function formatApproval(data) {
+    const request = data && data.request ? data.request : {};
+    return JSON.stringify({
+      type: APP_PROTOCOL.approvalRequest,
+      id: data.id,
+      requestId:
+        (data && typeof data.requestId === "string" && data.requestId) ||
+        (request && typeof request.requestId === "string" && request.requestId) ||
+        null,
+      command: request.command || "",
+      cwd: request.cwd || null,
+      agentId: request.agentId || null,
+      host: request.host || null,
+      security: request.security || null,
+      ask: request.ask || null,
+      resolvedPath: request.resolvedPath || null,
+      sessionKey: request.sessionKey || null,
+      createdAtMs: data.createdAtMs || 0,
+      expiresAtMs: data.expiresAtMs || 0,
+    });
+  }
+
+  /**
+   * Format an exec approval resolution for broadcast.
+   *
+   * @param {object} data - Resolution payload from gateway
+   * @returns {string} JSON string
+   */
+  function formatApprovalResolved(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.approvalResolved,
+      id: data.id,
+      requestId:
+        data && typeof data.requestId === "string" && data.requestId
+          ? data.requestId
+          : null,
+      decision: data.decision || null,
+    });
+  }
+
+  /**
+   * Format an approval-response acknowledgement for unicast.
+   *
+   * @param {object} data
+   * @returns {string}
+   */
+  function formatApprovalResponseAck(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.approvalResolveAck,
+      id: data && data.id ? data.id : null,
+      decision: data && data.decision ? data.decision : null,
+      requestId:
+        data && data.requestId !== undefined && data.requestId !== null
+          ? data.requestId
+          : null,
+      status:
+        data && typeof data.status === "string" && data.status
+          ? data.status
+          : "rejected",
+      code:
+        data && typeof data.code === "string" && data.code
+          ? data.code
+          : null,
+      message:
+        data && typeof data.message === "string" && data.message
+          ? data.message
+          : null,
+      idempotent:
+        data && data.idempotent !== undefined
+          ? !!data.idempotent
+          : false,
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @param {string} text - Final committed text sent upstream
+   * @param {"manual"|"endpoint"} source - Commit source path
+   * @param {string|null} sessionKey - Active relay session key for diagnostics
+   * @returns {string} JSON string
+   */
+  function formatListenCommitted(text, source, sessionKey) {
+    return JSON.stringify({
+      type: "listen-committed",
+      text,
+      source,
+      sessionKey: sessionKey || null,
+    });
+  }
+
+  /**
+   * Format a listen-ended message for broadcast.
+   * @returns {string} JSON string
+   */
+  function formatListenEnded() {
+    return JSON.stringify({ type: "listen-ended" });
+  }
+
+  /**
+   * Format a listen-error message for broadcast.
+   * @param {string} error - Error description
+   * @param {string|null} [code] - Structured error code
+   * @returns {string} JSON string
+   */
+  function formatListenError(error, code = null) {
+    const msg = { type: "listen-error", error };
+    if (typeof code === "string" && code.trim()) {
+      msg.code = code.trim();
+    }
+    return JSON.stringify(msg);
+  }
+
+  /**
+   * Format a listen-ready message for broadcast (agent done, client can auto-restart).
+   * @returns {string} JSON string
+   */
+  function formatListenReady() {
+    return JSON.stringify({ type: "listen-ready" });
+  }
+
+  /**
+   * Format a temporary Soniox key lease for unicast back to the requesting client.
+   *
+   * @param {{voiceSessionId: string, temporaryKey: string, expiresAtMs: number}} payload
+   * @returns {string}
+   */
+  function formatSonioxTemporaryKey(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.sonioxTemporaryKey,
+      voiceSessionId:
+        payload && typeof payload.voiceSessionId === "string"
+          ? payload.voiceSessionId
+          : "",
+      temporaryKey:
+        payload && typeof payload.temporaryKey === "string"
+          ? payload.temporaryKey
+          : "",
+      expiresAtMs:
+        payload && Number.isFinite(payload.expiresAtMs)
+          ? Math.floor(payload.expiresAtMs)
+          : 0,
+    });
+  }
+
+  /**
+   * Format a Soniox temporary-key failure for unicast back to the requesting client.
+   *
+   * @param {{voiceSessionId: string, error: string, code?: string|null}} payload
+   * @returns {string}
+   */
+  function formatSonioxTemporaryKeyError(payload) {
+    const msg = {
+      type: APP_PROTOCOL.sonioxTemporaryKeyError,
+      voiceSessionId:
+        payload && typeof payload.voiceSessionId === "string"
+          ? payload.voiceSessionId
+          : "",
+      error:
+        payload && typeof payload.error === "string" && payload.error.trim()
+          ? payload.error.trim()
+          : "Soniox temporary-key request failed",
+    };
+    const code =
+      payload && typeof payload.code === "string" && payload.code.trim()
+        ? payload.code.trim()
+        : "";
+    if (code) {
+      msg.code = code;
+    }
+    return JSON.stringify(msg);
+  }
+
+  function normalizeSonioxTemporaryKeyErrorCode(err) {
+    const message =
+      err && typeof err.message === "string" && err.message.trim()
+        ? err.message.trim()
+        : "";
+    const lowered = message.toLowerCase();
+    if (!message) return "soniox_temp_key_request_failed";
+    if (lowered.includes("is not available")) {
+      return "soniox_temp_key_unavailable";
+    }
+    if (lowered.includes("voicesessionid is required")) {
+      return "soniox_temp_key_invalid_request";
+    }
+    if (lowered.includes("api key is not configured")) {
+      return "soniox_temp_key_not_configured";
+    }
+    if (lowered.includes("fetch is not available")) {
+      return "soniox_temp_key_fetch_unavailable";
+    }
+    if (lowered.includes("missing temporarykey") || lowered.includes("missing expiresatms")) {
+      return "soniox_temp_key_invalid_response";
+    }
+    const statusMatch = lowered.match(/\((\d{3})\)/);
+    if (statusMatch) {
+      return `soniox_temp_key_http_${statusMatch[1]}`;
+    }
+    return "soniox_temp_key_request_failed";
+  }
+
+  /**
+   * Format a debug-set response for unicast.
+   *
+   * @param {object} data
+   * @returns {string}
+   */
+  function formatDebugSet(data) {
+    return JSON.stringify({
+      type: "debug-set",
+      ...data,
+    });
+  }
+
+  /**
+   * Format a debug-dump response for unicast.
+   *
+   * @param {object} data
+   * @returns {string}
+   */
+  function formatDebugDump(data) {
+    return JSON.stringify({
+      type: "debug-dump",
+      ...data,
+    });
+  }
+
+  /**
+   * Format the current relay debug-config snapshot for app/WebUI clients.
+   *
+   * @param {{serverNowMs: number, enabled: Array<{cat: string, expiresAtMs: number}>}} data
+   * @returns {string}
+   */
+  function formatDebugConfigSnapshot(data) {
+    const enabled = Array.isArray(data && data.enabled)
+      ? data.enabled
+          .filter(
+            (entry) =>
+              entry &&
+              typeof entry.cat === "string" &&
+              entry.cat.trim() &&
+              Number.isFinite(Number(entry.expiresAtMs)),
+          )
+          .map((entry) => ({
+            cat: entry.cat.trim(),
+            expiresAtMs: Math.floor(Number(entry.expiresAtMs)),
+          }))
+      : [];
+    return JSON.stringify({
+      type: APP_PROTOCOL.debugConfigSnapshot,
+      serverNowMs:
+        Number.isFinite(data && data.serverNowMs)
+          ? Math.floor(data.serverNowMs)
+          : 0,
+      enabled,
+    });
+  }
+
+  /**
+   * Format a remote-control command for broadcast to app clients.
+   *
+   * @param {object} data
+   * @returns {string}
+   */
+  function formatRemoteControl(data) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.remoteControl,
+      ...data,
+    });
+  }
+
+  /**
+   * Format a remote-control acknowledgement for unicast.
+   *
+   * @param {object} data
+   * @returns {string}
+   */
+  function formatRemoteControlAck(data) {
+    return JSON.stringify({
+      type: "remote-control-ack",
+      ...data,
+    });
+  }
+
+  function normalizeCategories(raw, fieldName) {
+    if (raw === undefined || raw === null) return [];
+    if (!Array.isArray(raw)) {
+      throw new Error(`${fieldName} must be an array`);
+    }
+    const dedup = new Set();
+    for (const entry of raw) {
+      if (typeof entry !== "string") {
+        throw new Error(`${fieldName} entries must be strings`);
+      }
+      const cat = entry.trim();
+      if (!cat) {
+        throw new Error(`${fieldName} entries must be non-empty strings`);
+      }
+      dedup.add(cat);
+    }
+    return Array.from(dedup.values());
+  }
+
+  function parseDebugSet(msg) {
+    const hasEnableDisable = msg.enable !== undefined || msg.disable !== undefined;
+    const enable = hasEnableDisable
+      ? normalizeCategories(msg.enable, "enable")
+      : msg.enabled === false
+        ? []
+        : normalizeCategories(msg.categories, "categories");
+    const disable = hasEnableDisable
+      ? normalizeCategories(msg.disable, "disable")
+      : msg.enabled === false
+        ? normalizeCategories(msg.categories, "categories")
+        : [];
+    if (enable.length === 0 && disable.length === 0) {
+      throw new Error("debug-set requires categories to enable and/or disable");
+    }
+    if (
+      msg.ttlMs !== undefined &&
+      (!Number.isFinite(Number(msg.ttlMs)) || Number(msg.ttlMs) <= 0)
+    ) {
+      throw new Error("debug-set ttlMs must be a positive number");
+    }
+    return {
+      enable,
+      disable,
+      ttlMs: msg.ttlMs === undefined ? undefined : Number(msg.ttlMs),
+    };
+  }
+
+  function parseDebugDump(msg) {
+    const categories = normalizeCategories(msg.categories, "categories");
+    if (
+      msg.limit !== undefined &&
+      (!Number.isFinite(Number(msg.limit)) || Number(msg.limit) <= 0)
+    ) {
+      throw new Error("debug-dump limit must be a positive number");
+    }
+    if (
+      msg.sinceMs !== undefined &&
+      (!Number.isFinite(Number(msg.sinceMs)) || Number(msg.sinceMs) < 0)
+    ) {
+      throw new Error("debug-dump sinceMs must be a non-negative number");
+    }
+    if (
+      msg.sinceAgeMs !== undefined &&
+      (!Number.isFinite(Number(msg.sinceAgeMs)) || Number(msg.sinceAgeMs) < 0)
+    ) {
+      throw new Error("debug-dump sinceAgeMs must be a non-negative number");
+    }
+    if (
+      msg.untilMs !== undefined &&
+      (!Number.isFinite(Number(msg.untilMs)) || Number(msg.untilMs) < 0)
+    ) {
+      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(),
+    };
+  }
+
+  function parseEventDebug(msg) {
+    if (!msg || typeof msg !== "object") return null;
+    if (typeof msg.cat !== "string" || !msg.cat.trim()) return null;
+    if (typeof msg.event !== "string" || !msg.event.trim()) return null;
+    const severity =
+      msg.severity === "info" ||
+      msg.severity === "warn" ||
+      msg.severity === "error"
+        ? msg.severity
+        : "debug";
+    return {
+      cat: msg.cat.trim(),
+      event: msg.event.trim(),
+      severity,
+      screen:
+        typeof msg.screen === "string" && msg.screen.trim()
+          ? msg.screen.trim()
+          : null,
+      runId:
+        typeof msg.runId === "string" && msg.runId.trim()
+          ? msg.runId.trim()
+          : null,
+      sessionKey:
+        typeof msg.sessionKey === "string" && msg.sessionKey.trim()
+          ? msg.sessionKey.trim()
+          : null,
+      data:
+        msg.data && typeof msg.data === "object" && !Array.isArray(msg.data)
+          ? msg.data
+          : { value: msg.data ?? null },
+    };
+  }
+
+  function normalizeRemoteButton(raw) {
+    if (typeof raw !== "string" || !raw.trim()) {
+      throw new Error("remote-control button is required");
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (
+      normalized === "click" ||
+      normalized === "tap" ||
+      normalized === "double-click" ||
+      normalized === "double_click" ||
+      normalized === "doubleclick" ||
+      normalized === "double-tap" ||
+      normalized === "double_tap" ||
+      normalized === "doubletap" ||
+      normalized === "scroll-up" ||
+      normalized === "scroll_up" ||
+      normalized === "scrollup" ||
+      normalized === "up" ||
+      normalized === "scroll-down" ||
+      normalized === "scroll_down" ||
+      normalized === "scrolldown" ||
+      normalized === "down"
+    ) {
+      if (normalized === "tap") return "click";
+      if (
+        normalized === "double_click" ||
+        normalized === "doubleclick" ||
+        normalized === "double-tap" ||
+        normalized === "double_tap" ||
+        normalized === "doubletap"
+      ) {
+        return "double-click";
+      }
+      if (normalized === "scroll_up" || normalized === "scrollup" || normalized === "up") {
+        return "scroll-up";
+      }
+      if (normalized === "scroll_down" || normalized === "scrolldown" || normalized === "down") {
+        return "scroll-down";
+      }
+      return normalized;
+    }
+    throw new Error(`unsupported remote-control button: ${raw}`);
+  }
+
+  function normalizeRemoteRelayAction(raw) {
+    if (typeof raw !== "string" || !raw.trim()) {
+      throw new Error("remote-control relayAction is required");
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (
+      normalized === "perf-conversation-upgrade-probe" ||
+      normalized === "perf_conversation_upgrade_probe" ||
+      normalized === "perfconversationupgradeprobe" ||
+      normalized === "conversation-upgrade-probe" ||
+      normalized === "conversation_upgrade_probe" ||
+      normalized === "conversationupgradeprobe"
+    ) {
+      return "perf-conversation-upgrade-probe";
+    }
+    if (
+      normalized === "new-session" ||
+      normalized === "new_session" ||
+      normalized === "newsession"
+    ) {
+      return "new-session";
+    }
+    if (
+      normalized === "get-sessions" ||
+      normalized === "get_sessions" ||
+      normalized === "getsessions" ||
+      normalized === "sessions"
+    ) {
+      return "get-sessions";
+    }
+    if (
+      normalized === "switch-session" ||
+      normalized === "switch_session" ||
+      normalized === "switchsession"
+    ) {
+      return "switch-session";
+    }
+    if (normalized === "new-chat" || normalized === "new_chat" || normalized === "newchat") {
+      return "new-chat";
+    }
+    if (
+      normalized === "slash-command" ||
+      normalized === "slash_command" ||
+      normalized === "slash"
+    ) {
+      return "slash-command";
+    }
+    if (
+      normalized === "listen-start" ||
+      normalized === "listen_start" ||
+      normalized === "listenstart"
+    ) {
+      return "listen-start";
+    }
+    if (
+      normalized === "listen-stop" ||
+      normalized === "listen_stop" ||
+      normalized === "listenstop"
+    ) {
+      return "listen-stop";
+    }
+    if (
+      normalized === "listen-send" ||
+      normalized === "listen_send" ||
+      normalized === "listensend"
+    ) {
+      return "listen-send";
+    }
+    if (
+      normalized === "listen-retry" ||
+      normalized === "listen_retry" ||
+      normalized === "listenretry"
+    ) {
+      return "listen-retry";
+    }
+    if (
+      normalized === "perf-reset-ladder" ||
+      normalized === "perf_reset_ladder" ||
+      normalized === "perfresetladder" ||
+      normalized === "reset-ladder" ||
+      normalized === "reset_ladder" ||
+      normalized === "resetladder"
+    ) {
+      return "perf-reset-ladder";
+    }
+    if (
+      normalized === "perf-relay-reconnect-only" ||
+      normalized === "perf_relay_reconnect_only" ||
+      normalized === "perfrelayreconnectonly" ||
+      normalized === "relay-reconnect-only" ||
+      normalized === "relay_reconnect_only" ||
+      normalized === "relayreconnectonly"
+    ) {
+      return "perf-relay-reconnect-only";
+    }
+    if (
+      normalized === "perf-sdk-page-recreate-only" ||
+      normalized === "perf_sdk_page_recreate_only" ||
+      normalized === "perfsdkpagerecreateonly" ||
+      normalized === "sdk-page-recreate-only" ||
+      normalized === "sdk_page_recreate_only" ||
+      normalized === "sdkpagerecreateonly"
+    ) {
+      return "perf-sdk-page-recreate-only";
+    }
+    if (
+      normalized === "perf-config" ||
+      normalized === "perf_config" ||
+      normalized === "perfconfig" ||
+      normalized === "perf-drift-config" ||
+      normalized === "perf_drift_config" ||
+      normalized === "perfdriftconfig"
+    ) {
+      return "perf-config";
+    }
+    if (
+      normalized === "debug-close-app-client" ||
+      normalized === "debug_close_app_client" ||
+      normalized === "debugcloseappclient" ||
+      normalized === "close-app-client" ||
+      normalized === "close_app_client" ||
+      normalized === "closeappclient"
+    ) {
+      return "debug-close-app-client";
+    }
+    throw new Error(`unsupported remote relayAction: ${raw}`);
+  }
+
+  function parseOptionalTrimmedString(raw) {
+    if (typeof raw !== "string") return null;
+    const trimmed = raw.trim();
+    return trimmed || null;
+  }
+
+  function parseOptionalBoolean(raw, fieldName) {
+    if (raw === undefined || raw === null) return undefined;
+    if (typeof raw === "boolean") return raw;
+    if (typeof raw === "number") return raw !== 0;
+    if (typeof raw !== "string") {
+      throw new Error(`${fieldName} must be a boolean`);
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (["true", "1", "yes", "y", "on"].includes(normalized)) return true;
+    if (["false", "0", "no", "n", "off"].includes(normalized)) return false;
+    throw new Error(`${fieldName} must be a boolean`);
+  }
+
+  function parseOptionalPositiveNumber(raw, fieldName) {
+    if (raw === undefined || raw === null) return undefined;
+    const num = Number(raw);
+    if (!Number.isFinite(num) || num <= 0) {
+      throw new Error(`${fieldName} must be a positive number`);
+    }
+    return Math.floor(num);
+  }
+
+  function parseOptionalNonNegativeNumber(raw, fieldName) {
+    if (raw === undefined || raw === null) return undefined;
+    const num = Number(raw);
+    if (!Number.isFinite(num) || num < 0) {
+      throw new Error(`${fieldName} must be a non-negative number`);
+    }
+    return Math.floor(num);
+  }
+
+  function parseOptionalStringArray(raw, fieldName) {
+    if (raw === undefined || raw === null) return undefined;
+    if (!Array.isArray(raw)) {
+      throw new Error(`${fieldName} must be an array of strings`);
+    }
+    const values = [];
+    for (const entry of raw) {
+      if (typeof entry !== "string") {
+        throw new Error(`${fieldName} must be an array of strings`);
+      }
+      const trimmed = entry.trim();
+      if (trimmed) values.push(trimmed);
+    }
+    return values;
+  }
+
+  function parseSetSessionModelConfig(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("setSessionModelConfig payload must be an object");
+    }
+
+    const payload = {};
+
+    const modelRef = parseOptionalTrimmedString(msg.modelRef);
+    if (modelRef) {
+      if (!modelRef.includes("/")) {
+        throw new Error("modelRef must be in provider/id format");
+      }
+      payload.modelRef = modelRef;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "thinkingLevel")) {
+      if (typeof msg.thinkingLevel !== "string") {
+        throw new Error(
+          "thinkingLevel must be blank|off|minimal|low|medium|high|xhigh",
+        );
+      }
+      const normalized = msg.thinkingLevel.trim().toLowerCase();
+      if (
+        normalized &&
+        !["off", "minimal", "low", "medium", "high", "xhigh"].includes(normalized)
+      ) {
+        throw new Error(
+          "thinkingLevel must be blank|off|minimal|low|medium|high|xhigh",
+        );
+      }
+      payload.thinkingLevel = normalized;
+    }
+
+    const reasoningEnabled = parseOptionalBoolean(
+      msg.reasoningEnabled,
+      "reasoningEnabled",
+    );
+    if (reasoningEnabled !== undefined) {
+      payload.reasoningEnabled = reasoningEnabled;
+    }
+
+    const verboseLevel = parseOptionalTrimmedString(msg.verboseLevel);
+    if (verboseLevel) {
+      const normalized = verboseLevel.toLowerCase();
+      if (!["off", "on", "full"].includes(normalized)) {
+        throw new Error("verboseLevel must be off|on|full");
+      }
+      payload.verboseLevel = normalized;
+    }
+
+    if (Object.keys(payload).length === 0) {
+      throw new Error("setSessionModelConfig requires at least one field");
+    }
+
+    return payload;
+  }
+
+  function parseSetEvenAiSettings(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("setEvenAiSettings payload must be an object");
+    }
+
+    const payload = {};
+
+    if (Object.prototype.hasOwnProperty.call(msg, "routingMode")) {
+      const routingMode = parseOptionalTrimmedString(msg.routingMode);
+      if (!routingMode) {
+        throw new Error("routingMode must be active|background|background_new");
+      }
+      const normalizedInput = routingMode.toLowerCase();
+      if (
+        ![
+          "active",
+          "background",
+          "background_new",
+          "dedicated",
+          "new",
+          "dedicated_shadow",
+          "new_shadow",
+        ].includes(normalizedInput)
+      ) {
+        throw new Error("routingMode must be active|background|background_new");
+      }
+      payload.routingMode = normalizeEvenAiRoutingMode(routingMode);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "systemPrompt")) {
+      if (typeof msg.systemPrompt !== "string") {
+        throw new Error("systemPrompt must be a string");
+      }
+      payload.systemPrompt = msg.systemPrompt.trim();
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultModel")) {
+      if (typeof msg.defaultModel !== "string") {
+        throw new Error("defaultModel must be a string");
+      }
+      payload.defaultModel = msg.defaultModel.trim();
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultThinking")) {
+      if (typeof msg.defaultThinking !== "string") {
+        throw new Error("defaultThinking must be a string");
+      }
+      const normalizedThinking = msg.defaultThinking.trim().toLowerCase();
+      if (
+        normalizedThinking &&
+        !["off", "minimal", "low", "medium", "high", "xhigh"].includes(normalizedThinking)
+      ) {
+        throw new Error("defaultThinking must be off|minimal|low|medium|high|xhigh");
+      }
+      payload.defaultThinking = normalizedThinking;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "listenEnabled")) {
+      if (typeof msg.listenEnabled !== "boolean") {
+        throw new Error("listenEnabled must be a boolean");
+      }
+      payload.listenEnabled = msg.listenEnabled;
+    }
+
+    if (Object.keys(payload).length === 0) {
+      throw new Error("setEvenAiSettings requires at least one field");
+    }
+
+    return payload;
+  }
+
+  function parseSetOcuClawSettings(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("setOcuClawSettings payload must be an object");
+    }
+
+    const payload = {};
+
+    if (Object.prototype.hasOwnProperty.call(msg, "systemPrompt")) {
+      if (typeof msg.systemPrompt !== "string") {
+        throw new Error("systemPrompt must be a string");
+      }
+      payload.systemPrompt = msg.systemPrompt.trim();
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultModel")) {
+      if (typeof msg.defaultModel !== "string") {
+        throw new Error("defaultModel must be a string");
+      }
+      payload.defaultModel = normalizeOcuClawDefaultModel(msg.defaultModel);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultThinking")) {
+      if (typeof msg.defaultThinking !== "string") {
+        throw new Error("defaultThinking must be a string");
+      }
+      payload.defaultThinking = normalizeOcuClawDefaultThinking(msg.defaultThinking);
+    }
+
+    if (Object.keys(payload).length === 0) {
+      throw new Error("setOcuClawSettings requires at least one field");
+    }
+
+    return payload;
+  }
+
+  function parseRequestSonioxTemporaryKey(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("requestSonioxTemporaryKey payload must be an object");
+    }
+
+    const voiceSessionId = parseOptionalTrimmedString(msg.voiceSessionId);
+    if (!voiceSessionId) {
+      throw new Error("voiceSessionId is required");
+    }
+
+    return {
+      voiceSessionId,
+      sessionKey: parseOptionalTrimmedString(msg.sessionKey),
+    };
+  }
+
+  function parseApprovalResponsePayload(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("ocuclaw.approval.resolve payload must be an object");
+    }
+    const id = parseOptionalTrimmedString(msg.id);
+    if (!id) {
+      throw new Error("ocuclaw.approval.resolve id is required");
+    }
+    const decisionRaw = parseOptionalTrimmedString(msg.decision);
+    if (!decisionRaw) {
+      throw new Error("ocuclaw.approval.resolve decision is required");
+    }
+    const decision = decisionRaw.toLowerCase();
+    if (!APPROVAL_DECISIONS.has(decision)) {
+      throw new Error(
+        "ocuclaw.approval.resolve decision must be allow-once|allow-always|deny",
+      );
+    }
+    return {
+      id,
+      decision,
+      requestId: parseOptionalTrimmedString(msg.requestId) || null,
+    };
+  }
+
+  function pruneApprovalResolveCache(nowMs) {
+    for (const [key, entry] of approvalResolveCache) {
+      if (!entry || entry.expiresAtMs <= nowMs) {
+        approvalResolveCache.delete(key);
+      }
+    }
+    while (approvalResolveCache.size > approvalResolveCacheMaxEntries) {
+      const oldest = approvalResolveCache.keys().next();
+      if (oldest.done) break;
+      approvalResolveCache.delete(oldest.value);
+    }
+  }
+
+  function parseRemoteControl(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("remote-control payload must be an object");
+    }
+    const actionRaw = parseOptionalTrimmedString(msg.action);
+    if (!actionRaw) {
+      throw new Error("remote-control action is required");
+    }
+
+    const action = actionRaw.toLowerCase();
+    const payload = {
+      action,
+      requestId: parseOptionalTrimmedString(msg.requestId) || null,
+    };
+
+    if (action === "button") {
+      payload.button = normalizeRemoteButton(msg.button);
+      return payload;
+    }
+
+    if (action === "send-message") {
+      const text = typeof msg.text === "string" ? msg.text : "";
+      if (!text.trim()) {
+        throw new Error("remote-control send-message requires non-empty text");
+      }
+      payload.text = text;
+      const sessionKey = parseOptionalTrimmedString(msg.sessionKey);
+      if (sessionKey) payload.sessionKey = sessionKey;
+      return payload;
+    }
+
+    if (action === "relay-action") {
+      payload.relayAction = normalizeRemoteRelayAction(msg.relayAction);
+      if (
+        payload.relayAction === "listen-start" ||
+        payload.relayAction === "listen-stop" ||
+        payload.relayAction === "listen-send" ||
+        payload.relayAction === "listen-retry"
+      ) {
+        throw new Error(
+          `remote-control relayAction ${payload.relayAction} was removed; voice stays local to the app`,
+        );
+      }
+      const sessionKey = parseOptionalTrimmedString(msg.sessionKey);
+      const command = parseOptionalTrimmedString(msg.command);
+      if (payload.relayAction === "switch-session" && !sessionKey) {
+        throw new Error("remote-control switch-session requires sessionKey");
+      }
+      if (payload.relayAction === "slash-command" && !command) {
+        throw new Error("remote-control slash-command requires command");
+      }
+      if (sessionKey) payload.sessionKey = sessionKey;
+      if (command) payload.command = command;
+      const endpointDetection = parseOptionalBoolean(msg.endpointDetection, "endpointDetection");
+      if (endpointDetection !== undefined) payload.endpointDetection = endpointDetection;
+      const maxEndpointDelayMs = parseOptionalPositiveNumber(
+        msg.maxEndpointDelayMs,
+        "maxEndpointDelayMs",
+      );
+      if (maxEndpointDelayMs !== undefined) payload.maxEndpointDelayMs = maxEndpointDelayMs;
+      const model = parseOptionalTrimmedString(msg.model);
+      if (model) payload.model = model;
+      const languageHints = parseOptionalStringArray(msg.languageHints, "languageHints");
+      if (languageHints !== undefined) payload.languageHints = languageHints;
+      return payload;
+    }
+
+    if (action === "list-click") {
+      const index = parseOptionalNonNegativeNumber(msg.index, "index");
+      if (index === undefined) {
+        throw new Error("remote-control list-click requires index");
+      }
+      payload.index = index;
+      const containerId = parseOptionalNonNegativeNumber(msg.containerId, "containerId");
+      const containerName = parseOptionalTrimmedString(msg.containerName);
+      if (containerId !== undefined) payload.containerId = containerId;
+      if (containerName) payload.containerName = containerName;
+      return payload;
+    }
+
+    if (action === "text-event") {
+      payload.eventType = normalizeRemoteButton(msg.eventType || msg.button);
+      const containerId = parseOptionalNonNegativeNumber(msg.containerId, "containerId");
+      const containerName = parseOptionalTrimmedString(msg.containerName);
+      if (containerId !== undefined) payload.containerId = containerId;
+      if (containerName) payload.containerName = containerName;
+      return payload;
+    }
+
+    throw new Error(`unsupported remote-control action: ${actionRaw}`);
+  }
+
+  const ATTACHMENT_MAX_DECODED_BYTES = 5_000_000;
+  const ATTACHMENT_MAX_ENCODED_CHARS =
+    Math.ceil((ATTACHMENT_MAX_DECODED_BYTES * 4) / 3) + 16;
+
+  function stripDataUrlPrefix(value) {
+    if (typeof value !== "string") return "";
+    if (!value.startsWith("data:")) return value;
+    const comma = value.indexOf(",");
+    return comma >= 0 ? value.slice(comma + 1) : value;
+  }
+
+  function parseOptionalPositiveInt(value) {
+    if (value === undefined || value === null) return null;
+    const num = Number(value);
+    if (!Number.isFinite(num) || num <= 0) return null;
+    return Math.floor(num);
+  }
+
+  function rejectAttachment(errorCode, error) {
+    return {
+      ok: false,
+      errorCode,
+      error,
+    };
+  }
+
+  function parseAttachment(rawAttachment) {
+    if (rawAttachment === undefined || rawAttachment === null) {
+      return { ok: true, attachment: null };
+    }
+    if (typeof rawAttachment !== "object" || Array.isArray(rawAttachment)) {
+      return rejectAttachment(
+        "attachment_invalid_type",
+        "attachment must be an object",
+      );
+    }
+
+    const kind = parseOptionalTrimmedString(rawAttachment.kind) || "image";
+    if (kind !== "image") {
+      return rejectAttachment(
+        "attachment_invalid_type",
+        "unsupported attachment kind",
+      );
+    }
+
+    const mimeTypeRaw = parseOptionalTrimmedString(rawAttachment.mimeType);
+    const mimeType = mimeTypeRaw ? mimeTypeRaw.toLowerCase() : null;
+    if (!mimeType || !mimeType.startsWith("image/")) {
+      return rejectAttachment(
+        "attachment_invalid_type",
+        "attachment mimeType must be image/*",
+      );
+    }
+
+    const base64Raw = parseOptionalTrimmedString(rawAttachment.base64Data);
+    if (!base64Raw) {
+      return rejectAttachment(
+        "attachment_missing_data",
+        "attachment base64Data is required",
+      );
+    }
+
+    const base64Data = stripDataUrlPrefix(base64Raw).replace(/\s+/g, "");
+    if (!base64Data) {
+      return rejectAttachment(
+        "attachment_missing_data",
+        "attachment base64Data is required",
+      );
+    }
+
+    if (base64Data.length > ATTACHMENT_MAX_ENCODED_CHARS) {
+      return rejectAttachment(
+        "attachment_too_large_encoded",
+        `attachment payload exceeds encoded limit (${ATTACHMENT_MAX_ENCODED_CHARS} chars)`,
+      );
+    }
+
+    if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64Data)) {
+      return rejectAttachment(
+        "attachment_decode_failed",
+        "attachment base64Data is not valid base64",
+      );
+    }
+
+    let decoded;
+    try {
+      decoded = Buffer.from(base64Data, "base64");
+    } catch {
+      return rejectAttachment(
+        "attachment_decode_failed",
+        "attachment base64Data decode failed",
+      );
+    }
+    if (!decoded || decoded.length <= 0) {
+      return rejectAttachment(
+        "attachment_missing_data",
+        "attachment decoded payload is empty",
+      );
+    }
+
+    const canonical = decoded.toString("base64").replace(/=+$/g, "");
+    const providedCanonical = base64Data.replace(/=+$/g, "");
+    if (canonical !== providedCanonical) {
+      return rejectAttachment(
+        "attachment_decode_failed",
+        "attachment base64Data decode failed",
+      );
+    }
+
+    if (decoded.length > ATTACHMENT_MAX_DECODED_BYTES) {
+      return rejectAttachment(
+        "attachment_too_large",
+        `attachment exceeds ${ATTACHMENT_MAX_DECODED_BYTES} byte decoded limit`,
+      );
+    }
+
+    const sourceRaw = parseOptionalTrimmedString(rawAttachment.source);
+    const sourceNormalized = sourceRaw ? sourceRaw.toLowerCase() : null;
+    const source =
+      sourceNormalized === "camera" || sourceNormalized === "gallery"
+        ? sourceNormalized
+        : null;
+
+    return {
+      ok: true,
+      attachment: {
+        kind: "image",
+        name: parseOptionalTrimmedString(rawAttachment.name) || "image.jpg",
+        mimeType,
+        base64Data,
+        sizeBytes: decoded.length,
+        widthPx: parseOptionalPositiveInt(rawAttachment.widthPx),
+        heightPx: parseOptionalPositiveInt(rawAttachment.heightPx),
+        source,
+      },
+    };
+  }
+
+  // --- Message handlers ---
+
+  /**
+   * Handle a "send" message: forward user text to upstream agent.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with id, text, sessionKey, and optional attachment
+   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
+   */
+  function handleSend(clientId, msg) {
+    const requestId = parseOptionalTrimmedString(msg.requestId);
+    if (!requestId) {
+      return {
+        unicast: formatSendAck(
+          requestId,
+          "rejected",
+          "Missing required field: requestId",
+        ),
+      };
+    }
+
+    const parsedAttachment = parseAttachment(msg.attachment);
+    if (!parsedAttachment.ok) {
+      return {
+        unicast: formatSendAck(
+          requestId,
+          "rejected",
+          parsedAttachment.error,
+          parsedAttachment.errorCode,
+        ),
+      };
+    }
+
+    const text = typeof msg.text === "string" ? msg.text : "";
+    if (!text.trim() && !parsedAttachment.attachment) {
+      return {
+        unicast: formatSendAck(
+          requestId,
+          "rejected",
+          "Missing required field: text",
+        ),
+      };
+    }
+
+    // Check upstream connectivity
+    if (!isUpstreamConnected()) {
+      return {
+        unicast: formatSendAck(
+          requestId,
+          "rejected",
+          "OpenClaw disconnected",
+        ),
+      };
+    }
+
+    // Forward to upstream — resolves on initial ack (accepted/queued)
+    return onSend(
+      requestId,
+      text,
+      msg.sessionKey || null,
+      parsedAttachment.attachment,
+    ).then(
+      (result) => {
+        const status = (result && result.status) || "accepted";
+        return { unicast: formatSendAck(requestId, status) };
+      },
+      (err) => ({
+        unicast: formatSendAck(
+          requestId,
+          "rejected",
+          err.message || "Send failed",
+          err.errorCode || undefined,
+        ),
+      }),
+    );
+  }
+
+  /**
+   * Handle a "simulate" message: inject fake message into conversation state.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with sender, text
+   * @returns {{ broadcast: string }}
+   */
+  function handleSimulate(clientId, msg) {
+    const pages = onSimulate(
+      msg.sender || "Simulator",
+      msg.text || "",
+    );
+    return { broadcast: formatPages(pages) };
+  }
+
+  /**
+   * Handle a "simulateStream" message: relay-local deterministic stream replay.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with id, text, sender, and timing controls.
+   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
+   */
+  function handleSimulateStream(clientId, msg) {
+    const id = parseOptionalTrimmedString(msg.id);
+    if (!id) {
+      return {
+        unicast: formatSendAck(
+          msg.id || null,
+          "rejected",
+          "Missing required field: id",
+        ),
+      };
+    }
+
+    if (!onSimulateStream) {
+      return {
+        unicast: formatSendAck(
+          id,
+          "rejected",
+          "simulateStream not supported by relay",
+        ),
+      };
+    }
+
+    const text = typeof msg.text === "string" ? msg.text : "";
+    if (!text.trim()) {
+      return {
+        unicast: formatSendAck(
+          id,
+          "rejected",
+          "simulateStream requires non-empty text",
+        ),
+      };
+    }
+
+    let chunkChars;
+    let chunkIntervalMs;
+    let startDelayMs;
+    let thinkingTailMs;
+    try {
+      chunkChars = parseOptionalPositiveNumber(msg.chunkChars, "chunkChars");
+      chunkIntervalMs = parseOptionalPositiveNumber(msg.chunkIntervalMs, "chunkIntervalMs");
+      startDelayMs = parseOptionalNonNegativeNumber(msg.startDelayMs, "startDelayMs");
+      thinkingTailMs = parseOptionalNonNegativeNumber(msg.thinkingTailMs, "thinkingTailMs");
+    } catch (err) {
+      return {
+        unicast: formatSendAck(
+          id,
+          "rejected",
+          err && err.message ? err.message : "Invalid simulateStream parameters",
+        ),
+      };
+    }
+
+    const request = {
+      id,
+      sender: parseOptionalTrimmedString(msg.sender) || "Simulator",
+      text,
+      sessionKey: parseOptionalTrimmedString(msg.sessionKey) || null,
+      chunkChars,
+      chunkIntervalMs,
+      startDelayMs,
+      thinkingTailMs,
+    };
+
+    return Promise.resolve(onSimulateStream(request)).then(
+      (result) => {
+        const status = result && result.status ? result.status : "accepted";
+        const error = result && result.error ? result.error : undefined;
+        return { unicast: formatSendAck(id, status, error) };
+      },
+      (err) => ({
+        unicast: formatSendAck(
+          id,
+          "rejected",
+          err && err.message ? err.message : "simulateStream failed",
+        ),
+      }),
+    );
+  }
+
+  /**
+   * Handle a "subscribeProtocol" message: mark client for protocol forwarding.
+   *
+   * @param {string} clientId
+   * @returns {null}
+   */
+  function handleSubscribeProtocol(clientId) {
+    protocolSubscribers.add(clientId);
+    return null;
+  }
+
+  /**
+   * Handle an "approvalResponse" message: forward decision to upstream gateway.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with id and decision
+   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
+   */
+  function handleApprovalResponse(clientId, msg) {
+    let payload;
+    try {
+      payload = parseApprovalResponsePayload(msg);
+    } catch (err) {
+      return {
+        unicast: formatApprovalResponseAck({
+          id: parseOptionalTrimmedString(msg && msg.id) || null,
+          decision: parseOptionalTrimmedString(msg && msg.decision) || null,
+          requestId: parseOptionalTrimmedString(msg && msg.requestId) || null,
+          status: "rejected",
+          code: "invalid_approval_response",
+          message:
+            err && err.message
+              ? err.message
+              : "Invalid ocuclaw.approval.resolve payload",
+          idempotent: false,
+        }),
+      };
+    }
+
+    if (!onApprovalResolve) {
+      return {
+        unicast: formatApprovalResponseAck({
+          id: payload.id,
+          decision: payload.decision,
+          requestId: payload.requestId,
+          status: "rejected",
+          code: "approval_unavailable",
+          message: "approval resolution is not available",
+          idempotent: false,
+        }),
+      };
+    }
+
+    const nowMs = Date.now();
+    pruneApprovalResolveCache(nowMs);
+    const idempotencyScope = payload.requestId || `client:${clientId}`;
+    const cacheKey = `${payload.id}|${payload.decision}|${idempotencyScope}`;
+    const existing = approvalResolveCache.get(cacheKey);
+    if (existing && existing.expiresAtMs > nowMs) {
+      existing.expiresAtMs = nowMs + approvalResolveCacheTtlMs;
+      return existing.promise.then((ack) => ({
+        unicast: formatApprovalResponseAck({
+          ...ack,
+          idempotent: true,
+          code:
+            ack && ack.status === "accepted"
+              ? "duplicate_request"
+              : ack && ack.code
+                ? ack.code
+                : "duplicate_request",
+        }),
+      }));
+    }
+
+    const promise = Promise.resolve(
+      onApprovalResolve(
+        payload.id,
+        payload.decision,
+        { requestId: payload.requestId, clientId },
+      ),
+    ).then(
+      () => ({
+        id: payload.id,
+        decision: payload.decision,
+        requestId: payload.requestId,
+        status: "accepted",
+        code: "ok",
+        message: null,
+        idempotent: false,
+      }),
+      (err) => {
+        const message =
+          err && err.message ? err.message : "approvalResolve failed";
+        logger.error(`[downstream] approvalResolve failed: ${message}`);
+        return {
+          id: payload.id,
+          decision: payload.decision,
+          requestId: payload.requestId,
+          status: "rejected",
+          code: "approval_resolve_failed",
+          message,
+          idempotent: false,
+        };
+      },
+    );
+
+    const cacheEntry = {
+      expiresAtMs: nowMs + approvalResolveCacheTtlMs,
+      promise,
+    };
+    approvalResolveCache.set(cacheKey, cacheEntry);
+    pruneApprovalResolveCache(nowMs);
+
+    return promise.then((ack) => {
+      if (ack && ack.status === "accepted") {
+        cacheEntry.expiresAtMs = Date.now() + approvalResolveCacheTtlMs;
+      } else {
+        approvalResolveCache.delete(cacheKey);
+      }
+      return { unicast: formatApprovalResponseAck(ack) };
+    });
+  }
+
+  /**
+   * Handle a "newChat" message: clear conversation and reset the session.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ broadcast: string }>}
+   */
+  function handleNewChat(clientId) {
+    return onNewChat().then(
+      (pages) => ({ broadcast: formatPages(pages) }),
+      (err) => {
+        logger.error(`[downstream] newChat failed: ${err.message}`);
+        return null;
+      },
+    );
+  }
+
+  /**
+   * Handle a "getSessions" message: fetch session list from upstream.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>}
+   */
+  function handleGetSessions(clientId) {
+    return onGetSessions().then(
+      (sessions) => ({ unicast: formatSessions(sessions) }),
+      (err) => {
+        logger.error(`[downstream] getSessions failed: ${err.message}`);
+        return { unicast: formatSessions([]) };
+      },
+    );
+  }
+
+  /**
+   * Handle "getModelsCatalog": return cached model catalog snapshot.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetModelsCatalog(clientId) {
+    if (!onGetModelsCatalog) {
+      return {
+        unicast: formatModelsCatalog({
+          models: [],
+          fetchedAtMs: Date.now(),
+          stale: true,
+        }),
+      };
+    }
+    return Promise.resolve(onGetModelsCatalog()).then(
+      (payload) => ({
+        unicast: formatModelsCatalog(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getModelsCatalog failed: ${err.message}`);
+        return {
+          unicast: formatModelsCatalog({
+            models: [],
+            fetchedAtMs: Date.now(),
+            stale: true,
+          }),
+        };
+      },
+    );
+  }
+
+  /**
+   * Handle "getSkills": return cached skills catalog snapshot.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetSkillsCatalog(clientId) {
+    if (!onGetSkillsCatalog) {
+      return {
+        unicast: formatSkillsCatalog({
+          skills: [],
+          fetchedAtMs: Date.now(),
+          stale: true,
+        }),
+      };
+    }
+    return Promise.resolve(onGetSkillsCatalog()).then(
+      (payload) => ({
+        unicast: formatSkillsCatalog(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getSkills failed: ${err.message}`);
+        return {
+          unicast: formatSkillsCatalog({
+            skills: [],
+            fetchedAtMs: Date.now(),
+            stale: true,
+          }),
+        };
+      },
+    );
+  }
+
+  /**
+   * Handle "getSonioxModels": return cached Soniox model snapshot.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetSonioxModels(clientId) {
+    if (!onGetSonioxModels) {
+      return {
+        unicast: formatSonioxModels({
+          models: [],
+          fetchedAtMs: Date.now(),
+          stale: true,
+        }),
+      };
+    }
+    return Promise.resolve(onGetSonioxModels()).then(
+      (payload) => ({
+        unicast: formatSonioxModels(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getSonioxModels failed: ${err.message}`);
+        return {
+          unicast: formatSonioxModels({
+            models: [],
+            fetchedAtMs: Date.now(),
+            stale: true,
+          }),
+        };
+      },
+    );
+  }
+
+  /**
+   * Handle "getStatus": return the current status snapshot.
+   *
+   * @param {string} clientId
+   * @returns {{ unicast: string }}
+   */
+  function handleGetStatus(clientId) {
+    if (!onGetStatus) {
+      return { unicast: formatError("getStatus is not available") };
+    }
+    try {
+      return {
+        unicast: formatStatus(onGetStatus() || {}),
+      };
+    } catch (err) {
+      return { unicast: formatError(err.message || "getStatus failed") };
+    }
+  }
+
+  /**
+   * Handle "getSessionModelConfig": read controls for current session key.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetSessionModelConfig(clientId) {
+    if (!onGetSessionModelConfig) {
+      return { unicast: formatError("getSessionModelConfig is not available") };
+    }
+    return Promise.resolve(onGetSessionModelConfig()).then(
+      (payload) => ({
+        unicast: formatSessionModelConfig(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getSessionModelConfig failed: ${err.message}`);
+        return { unicast: formatError(err.message || "getSessionModelConfig failed") };
+      },
+    );
+  }
+
+  /**
+   * Handle "setSessionModelConfig": patch controls for current session key.
+   *
+   * @param {string} clientId
+   * @param {object} msg
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleSetSessionModelConfig(clientId, msg) {
+    if (!onSetSessionModelConfig) {
+      return {
+        unicast: formatSessionModelConfigAck({
+          status: "rejected",
+          error: "setSessionModelConfig is not available",
+        }),
+      };
+    }
+
+    let payload;
+    try {
+      payload = parseSetSessionModelConfig(msg);
+    } catch (err) {
+      return {
+        unicast: formatSessionModelConfigAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "invalid setSessionModelConfig payload",
+        }),
+      };
+    }
+
+    return Promise.resolve(onSetSessionModelConfig(payload)).then(
+      (result) =>
+        ({
+          unicast: formatSessionModelConfigAck(result || { status: "accepted" }),
+        }),
+      (err) =>
+        ({
+          unicast: formatSessionModelConfigAck({
+            status: "rejected",
+            error: err && err.message ? err.message : "setSessionModelConfig failed",
+          }),
+        }),
+    );
+  }
+
+  /**
+   * Handle "getEvenAiSettings": read relay-owned Even AI settings.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetEvenAiSettings(clientId) {
+    if (!onGetEvenAiSettings) {
+      return { unicast: formatError("getEvenAiSettings is not available") };
+    }
+    return Promise.resolve(onGetEvenAiSettings()).then(
+      (payload) => ({
+        unicast: formatEvenAiSettings(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getEvenAiSettings failed: ${err.message}`);
+        return { unicast: formatError(err.message || "getEvenAiSettings failed") };
+      },
+    );
+  }
+
+  /**
+   * Handle "getEvenAiSessions": return tracked Even AI sessions.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetEvenAiSessions(clientId) {
+    if (!onGetEvenAiSessions) {
+      return { unicast: formatError("getEvenAiSessions is not available") };
+    }
+    return Promise.resolve(onGetEvenAiSessions()).then(
+      (payload) => ({
+        unicast: formatEvenAiSessions(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getEvenAiSessions failed: ${err.message}`);
+        return { unicast: formatEvenAiSessions({ sessions: [] }) };
+      },
+    );
+  }
+
+  /**
+   * Handle "setEvenAiSettings": patch relay-owned Even AI settings.
+   *
+   * @param {string} clientId
+   * @param {object} msg
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleSetEvenAiSettings(clientId, msg) {
+    if (!onSetEvenAiSettings) {
+      return {
+        unicast: formatEvenAiSettingsAck({
+          status: "rejected",
+          error: "setEvenAiSettings is not available",
+        }),
+      };
+    }
+
+    let payload;
+    try {
+      payload = parseSetEvenAiSettings(msg);
+    } catch (err) {
+      return {
+        unicast: formatEvenAiSettingsAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "invalid setEvenAiSettings payload",
+        }),
+      };
+    }
+
+    return Promise.resolve(onSetEvenAiSettings(payload)).then(
+      (result) => ({
+        unicast: formatEvenAiSettingsAck(result || { status: "accepted" }),
+      }),
+      (err) => ({
+        unicast: formatEvenAiSettingsAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "setEvenAiSettings failed",
+        }),
+      }),
+    );
+  }
+
+  /**
+   * Handle "getOcuClawSettings": read relay-owned OcuClaw settings.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleGetOcuClawSettings(clientId) {
+    if (!onGetOcuClawSettings) {
+      return { unicast: formatError("getOcuClawSettings is not available") };
+    }
+    return Promise.resolve(onGetOcuClawSettings()).then(
+      (payload) => ({
+        unicast: formatOcuClawSettings(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getOcuClawSettings failed: ${err.message}`);
+        return { unicast: formatError(err.message || "getOcuClawSettings failed") };
+      },
+    );
+  }
+
+  /**
+   * Handle "setOcuClawSettings": patch relay-owned OcuClaw settings.
+   *
+   * @param {string} clientId
+   * @param {object} msg
+   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
+   */
+  function handleSetOcuClawSettings(clientId, msg) {
+    if (!onSetOcuClawSettings) {
+      return {
+        unicast: formatOcuClawSettingsAck({
+          status: "rejected",
+          error: "setOcuClawSettings is not available",
+        }),
+      };
+    }
+
+    let payload;
+    try {
+      payload = parseSetOcuClawSettings(msg);
+    } catch (err) {
+      return {
+        unicast: formatOcuClawSettingsAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "invalid setOcuClawSettings payload",
+        }),
+      };
+    }
+
+    return Promise.resolve(onSetOcuClawSettings(payload)).then(
+      (result) => ({
+        unicast: formatOcuClawSettingsAck(result || { status: "accepted" }),
+      }),
+      (err) => ({
+        unicast: formatOcuClawSettingsAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "setOcuClawSettings failed",
+        }),
+      }),
+    );
+  }
+
+  /**
+   * Handle a "switchSession" message: switch to a different session.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with sessionKey
+   * @returns {Promise<{ broadcast: string[] }|null>}
+   */
+  function handleSwitchSession(clientId, msg) {
+    if (!msg.sessionKey) return null;
+    return onSwitchSession(msg.sessionKey).then(
+      (pages) => ({
+        broadcast: [
+          formatSessionSwitched(msg.sessionKey),
+          formatPages(pages),
+        ],
+      }),
+      (err) => {
+        logger.error(`[downstream] switchSession failed: ${err.message}`);
+        return null;
+      },
+    );
+  }
+
+  /**
+   * Handle a "newSession" message: create a new session.
+   *
+   * @param {string} clientId
+   * @returns {Promise<{ broadcast: string[] }|null>}
+   */
+  function handleNewSession(clientId) {
+    return onNewSession().then(
+      (result) => {
+        const broadcast = [
+          formatSessionSwitched(result.sessionKey),
+          formatPages(result.pages),
+        ];
+        if (result && result.sessionModelConfig) {
+          broadcast.push(formatSessionModelConfig(result.sessionModelConfig));
+        }
+        return { broadcast };
+      },
+      (err) => {
+        logger.error(`[downstream] newSession failed: ${err.message}`);
+        return null;
+      },
+    );
+  }
+
+  /**
+   * Handle a "slashCommand" message: forward a slash command to OpenClaw.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with command
+   * @returns {Promise<null>}
+   */
+  function handleSlashCommand(clientId, msg) {
+    if (!msg.command) return null;
+    return onSlashCommand(msg.command).then(
+      () => null,
+      (err) => {
+        logger.error(`[downstream] slashCommand failed: ${err.message}`);
+        return null;
+      },
+    );
+  }
+
+  /**
+   * Handle a "console" message: forward browser console output to log.
+   *
+   * @param {string} clientId
+   * @param {object} msg - Parsed message with level, message
+   * @returns {null}
+   */
+  function handleConsole(clientId, msg) {
+    if (onConsoleLog) {
+      onConsoleLog(msg.level || "log", msg.message || "");
+    }
+    return null;
+  }
+
+  /**
+   * Handle a structured "eventDebug" message.
+   *
+   * Legacy payloads (without cat/event) fall back to onConsoleLog.
+   */
+  function handleEventDebug(clientId, msg) {
+    const parsed = parseEventDebug(msg);
+    if (parsed && onEventDebug) {
+      onEventDebug(clientId, parsed);
+      return null;
+    }
+    if (onConsoleLog) {
+      const legacyMessage =
+        typeof msg.data === "string" ? msg.data : JSON.stringify(msg);
+      onConsoleLog("event", legacyMessage);
+    }
+    return null;
+  }
+
+  function handleRemovedListenAction(messageType) {
+    return {
+      unicast: formatError(
+        `${messageType} was removed; hybrid-local voice stays local to the app`,
+      ),
+    };
+  }
+
+  /**
+   * Handle a "requestSonioxTemporaryKey" message.
+   */
+  function handleRequestSonioxTemporaryKey(clientId, msg) {
+    let payload;
+    try {
+      payload = parseRequestSonioxTemporaryKey(msg);
+    } catch (err) {
+      return {
+        unicast: formatSonioxTemporaryKeyError({
+          voiceSessionId:
+            msg && typeof msg.voiceSessionId === "string" ? msg.voiceSessionId : "",
+          error: err && err.message ? err.message : "requestSonioxTemporaryKey failed",
+          code: normalizeSonioxTemporaryKeyErrorCode(err),
+        }),
+      };
+    }
+
+    if (!onRequestSonioxTemporaryKey) {
+      return {
+        unicast: formatSonioxTemporaryKeyError({
+          voiceSessionId: payload.voiceSessionId,
+          error: "requestSonioxTemporaryKey is not available",
+          code: "soniox_temp_key_unavailable",
+        }),
+      };
+    }
+
+    try {
+      const result = onRequestSonioxTemporaryKey(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => ({ unicast: formatSonioxTemporaryKey(resolved || payload) }),
+          (err) => {
+            const error =
+              err && err.message
+                ? err.message
+                : "requestSonioxTemporaryKey failed";
+            return {
+              unicast: formatSonioxTemporaryKeyError({
+                voiceSessionId: payload.voiceSessionId,
+                error,
+                code: normalizeSonioxTemporaryKeyErrorCode(err),
+              }),
+            };
+          },
+        );
+      }
+      return { unicast: formatSonioxTemporaryKey(result || payload) };
+    } catch (err) {
+      return {
+        unicast: formatSonioxTemporaryKeyError({
+          voiceSessionId: payload.voiceSessionId,
+          error: err && err.message ? err.message : "requestSonioxTemporaryKey failed",
+          code: normalizeSonioxTemporaryKeyErrorCode(err),
+        }),
+      };
+    }
+  }
+
+  /**
+   * Handle a "debug-set" message: enable/disable debug categories with TTL.
+   */
+  function handleDebugSet(clientId, msg) {
+    if (!onDebugSet) {
+      return { unicast: formatError("debug-set is not available") };
+    }
+
+    let payload;
+    try {
+      payload = parseDebugSet(msg);
+    } catch (err) {
+      return { unicast: formatError(err.message) };
+    }
+
+    try {
+      const result = onDebugSet(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => {
+            const payloadResult = resolved || { ok: true };
+            const out = { unicast: formatDebugSet(payloadResult) };
+            if (
+              payloadResult.ok !== false &&
+              Number.isFinite(payloadResult.nowMs) &&
+              Array.isArray(payloadResult.enabled)
+            ) {
+              out.broadcastApp = formatDebugConfigSnapshot({
+                serverNowMs: payloadResult.nowMs,
+                enabled: payloadResult.enabled,
+              });
+            }
+            return out;
+          },
+          (err) => ({ unicast: formatError(err.message || "debug-set failed") }),
+        );
+      }
+      const payloadResult = result || { ok: true };
+      const out = { unicast: formatDebugSet(payloadResult) };
+      if (
+        payloadResult.ok !== false &&
+        Number.isFinite(payloadResult.nowMs) &&
+        Array.isArray(payloadResult.enabled)
+      ) {
+        out.broadcastApp = formatDebugConfigSnapshot({
+          serverNowMs: payloadResult.nowMs,
+          enabled: payloadResult.enabled,
+        });
+      }
+      return out;
+    } catch (err) {
+      return { unicast: formatError(err.message || "debug-set failed") };
+    }
+  }
+
+  /**
+   * Handle a "debug-dump" message: fetch structured debug events.
+   */
+  function handleDebugDump(clientId, msg) {
+    if (!onDebugDump) {
+      return { unicast: formatError("debug-dump is not available") };
+    }
+
+    let payload;
+    try {
+      payload = parseDebugDump(msg);
+    } catch (err) {
+      return { unicast: formatError(err.message) };
+    }
+
+    try {
+      const result = onDebugDump(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => ({ unicast: formatDebugDump(resolved || { ok: true, events: [] }) }),
+          (err) => ({ unicast: formatError(err.message || "debug-dump failed") }),
+        );
+      }
+      return { unicast: formatDebugDump(result || { ok: true, events: [] }) };
+    } catch (err) {
+      return { unicast: formatError(err.message || "debug-dump failed") };
+    }
+  }
+
+  /**
+   * Handle a "remote-control" message: dispatch remote actions to app clients.
+   */
+  function handleRemoteControl(clientId, msg) {
+    if (!onRemoteControl) {
+      return { unicast: formatError("remote-control is not available") };
+    }
+
+    let payload;
+    try {
+      payload = parseRemoteControl(msg);
+    } catch (err) {
+      return { unicast: formatError(err.message) };
+    }
+
+    const finalize = (result) => {
+      const resolved = result || {};
+      const requestId = resolved.requestId || payload.requestId || null;
+      const ack = {
+        ok: resolved.ok !== false,
+        requestId,
+        action: payload.action,
+        dispatched: !!resolved.control,
+      };
+      if (resolved.message) ack.message = resolved.message;
+      if (resolved.detail) ack.detail = resolved.detail;
+
+      const out = {
+        unicast: formatRemoteControlAck(ack),
+      };
+      if (resolved.control) {
+        out.broadcast = formatRemoteControl(resolved.control);
+      }
+      return out;
+    };
+
+    try {
+      const result = onRemoteControl(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => finalize(resolved),
+          (err) => ({ unicast: formatError(err.message || "remote-control failed") }),
+        );
+      }
+      return finalize(result);
+    } catch (err) {
+      return { unicast: formatError(err.message || "remote-control failed") };
+    }
+  }
+
+  // --- Public API ---
+
+  return {
+    /**
+     * Process an incoming downstream message.
+     *
+     * @param {string} clientId - Identifier of the sending client
+     * @param {string} raw - Raw JSON string
+     * @returns {{ unicast: string }|{ broadcast: string }|null|Promise}
+     */
+    handleMessage(clientId, raw) {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return { unicast: formatError("Invalid JSON") };
+      }
+
+      if (
+        !externalDebugToolsEnabled &&
+        msg &&
+        typeof msg.type === "string" &&
+        isExternalDebugToolMessageType(msg.type)
+      ) {
+        return {
+          unicast: formatError(EXTERNAL_DEBUG_TOOLS_DISABLED_ERROR),
+        };
+      }
+
+      switch (msg.type) {
+        case APP_PROTOCOL.messageSend:
+          return handleSend(clientId, msg);
+        case "simulate":
+          return handleSimulate(clientId, msg);
+        case "simulateStream":
+          return handleSimulateStream(clientId, msg);
+        case APP_PROTOCOL.protocolSubscribe:
+          return handleSubscribeProtocol(clientId);
+        case APP_PROTOCOL.approvalResolve:
+          return handleApprovalResponse(clientId, msg);
+        case APP_PROTOCOL.sessionReset:
+          return handleNewChat(clientId);
+        case APP_PROTOCOL.sessionList:
+          return handleGetSessions(clientId);
+        case APP_PROTOCOL.sessionSwitch:
+          return handleSwitchSession(clientId, msg);
+        case APP_PROTOCOL.sessionCreate:
+          return handleNewSession(clientId);
+        case APP_PROTOCOL.modelCatalogGet:
+          return handleGetModelsCatalog(clientId);
+        case APP_PROTOCOL.skillsCatalogGet:
+        case "getSkills":
+          return handleGetSkillsCatalog(clientId);
+        case APP_PROTOCOL.sonioxModelsGet:
+        case "getSonioxModels":
+          return handleGetSonioxModels(clientId);
+        case APP_PROTOCOL.statusGet:
+        case "getStatus":
+          return handleGetStatus(clientId);
+        case APP_PROTOCOL.sessionConfigGet:
+          return handleGetSessionModelConfig(clientId);
+        case APP_PROTOCOL.sessionConfigSet:
+          return handleSetSessionModelConfig(clientId, msg);
+        case APP_PROTOCOL.evenAiSettingsGet:
+          return handleGetEvenAiSettings(clientId);
+        case APP_PROTOCOL.evenAiSessionList:
+          return handleGetEvenAiSessions(clientId);
+        case APP_PROTOCOL.evenAiSettingsSet:
+          return handleSetEvenAiSettings(clientId, msg);
+        case APP_PROTOCOL.ocuClawSettingsGet:
+          return handleGetOcuClawSettings(clientId);
+        case APP_PROTOCOL.ocuClawSettingsSet:
+          return handleSetOcuClawSettings(clientId, msg);
+        case APP_PROTOCOL.commandSlash:
+          return handleSlashCommand(clientId, msg);
+        case "console":
+          return handleConsole(clientId, msg);
+        case "listen-start":
+        case "listen-stop":
+        case "listen-send":
+        case "listen-retry":
+          return handleRemovedListenAction(msg.type);
+        case APP_PROTOCOL.requestSonioxTemporaryKey:
+          return handleRequestSonioxTemporaryKey(clientId, msg);
+        case "debug-set":
+          return handleDebugSet(clientId, msg);
+        case "debug-dump":
+          return handleDebugDump(clientId, msg);
+        case "remote-control":
+          return handleRemoteControl(clientId, msg);
+        case APP_PROTOCOL.debugEvent:
+          return handleEventDebug(clientId, msg);
+        default:
+          return null;
+      }
+    },
+
+    formatPages,
+    formatStatus,
+    formatActivity,
+    formatSendAck,
+    formatProtocol,
+    formatStreaming,
+    formatSessions,
+    formatSessionSwitched,
+    formatModelsCatalog,
+    formatSkillsCatalog,
+    formatSonioxModels,
+    formatSessionModelConfig,
+    formatSessionModelConfigAck,
+    formatEvenAiSettings,
+    formatOcuClawSettings,
+    formatEvenAiSessions,
+    formatEvenAiSettingsAck,
+    formatOcuClawSettingsAck,
+    formatApproval,
+    formatApprovalResolved,
+    formatApprovalResponseAck,
+    formatTranscription,
+    formatListenCommitted,
+    formatListenEnded,
+    formatListenError,
+    formatListenReady,
+    formatSonioxTemporaryKey,
+    formatSonioxTemporaryKeyError,
+    formatDebugSet,
+    formatDebugDump,
+    formatDebugConfigSnapshot,
+    formatRemoteControl,
+    formatRemoteControlAck,
+    formatError,
+
+    /**
+     * Check whether a client is subscribed to protocol frame forwarding.
+     *
+     * @param {string} clientId
+     * @returns {boolean}
+     */
+    isProtocolSubscriber(clientId) {
+      return protocolSubscribers.has(clientId);
+    },
+
+    /**
+     * Clean up state for a disconnected client.
+     *
+     * @param {string} clientId
+     */
+    removeClient(clientId) {
+      protocolSubscribers.delete(clientId);
+    },
+  };
+}
+
+export { createDownstreamHandler };