ocuclaw 0.1.0

package/dist/runtime/relay-core.js

@@ -0,0 +1,1977 @@
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as path from "node:path";
+import * as conversationStateModule from "../domain/conversation-state.js";
+import { createDebugStore } from "../domain/debug-store.js";
+import { composeReadabilitySystemPrompt } from "../domain/readability-system-prompt.js";
+import { createActivityStatusAdapter } from "../domain/activity-status-adapter.js";
+import { createEvenAiEndpoint } from "../even-ai/even-ai-endpoint.js";
+import { createEvenAiRouter } from "../even-ai/even-ai-router.js";
+import { createEvenAiRunWaiter } from "../even-ai/even-ai-run-waiter.js";
+import { createEvenAiSettingsStore } from "../even-ai/even-ai-settings-store.js";
+import { createPluginOpenclawClient } from "../gateway/openclaw-client.js";
+import { createPluginRpcGatewayBridge } from "../gateway/gateway-bridge.js";
+import { createDownstreamHandler } from "./downstream-handler.js";
+import { createDownstreamServer } from "./downstream-server.js";
+import { createOcuClawSettingsStore } from "./ocuclaw-settings-store.js";
+import { createSessionService } from "./session-service.js";
+import { createUpstreamRuntime } from "./upstream-runtime.js";
+
+const SONIOX_TEMP_KEY_URL = "https://api.soniox.com/v1/auth/temporary-api-key";
+const SONIOX_MODELS_URL = "https://api.soniox.com/v1/models";
+const DEFAULT_SONIOX_TEMP_KEY_EXPIRES_IN_SECONDS = 3600;
+const EVEN_AI_HANDLED = Symbol.for("ocuclaw.evenai.handled");
+const EVEN_AI_NAMESPACE_PREFIX = "ocuclaw:even-ai";
+const EVEN_AI_NAMESPACE_PREFIX_WITH_DELIMITER = "ocuclaw:even-ai:";
+const LISTEN_INTERCEPT_RECOVERY_ERROR = "Voice interrupted; retry";
+const LISTEN_INTERCEPT_RECOVERY_CODE = "transport_interrupted";
+
+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,
+  };
+}
+
+function pickTrimmedString(...values) {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (trimmed) return trimmed;
+  }
+  return "";
+}
+
+function tailForLog(value, maxChars = 160) {
+  const text =
+    typeof value === "string" ? value : value === undefined || value === null ? "" : String(value);
+  if (text.length <= maxChars) return text;
+  return text.slice(-maxChars);
+}
+
+function normalizeEvenAiSessionKeyForLookup(rawKey) {
+  if (typeof rawKey !== "string") return "";
+  const rawText = rawKey.trim();
+  if (!rawText) return "";
+  const rawTextLower = rawText.toLowerCase();
+  const prefixIndex = rawTextLower.indexOf("ocuclaw:");
+  const shortKey = prefixIndex >= 0 ? rawText.slice(prefixIndex) : rawText;
+  const shortKeyLower = shortKey.toLowerCase();
+  if (
+    shortKeyLower === EVEN_AI_NAMESPACE_PREFIX ||
+    shortKeyLower.startsWith(EVEN_AI_NAMESPACE_PREFIX_WITH_DELIMITER)
+  ) {
+    return shortKey;
+  }
+  return "";
+}
+
+function dedupeNormalizedSessionKeys(sessionKeys) {
+  if (!Array.isArray(sessionKeys) || sessionKeys.length === 0) {
+    return [];
+  }
+  const dedupe = new Set();
+  const normalized = [];
+  for (const rawKey of sessionKeys) {
+    const normalizedKey = normalizeEvenAiSessionKeyForLookup(rawKey);
+    if (!normalizedKey) continue;
+    const compareKey = normalizedKey.toLowerCase();
+    if (dedupe.has(compareKey)) continue;
+    dedupe.add(compareKey);
+    normalized.push(normalizedKey);
+  }
+  return normalized;
+}
+
+function parseExpiryMs(raw, nowMs) {
+  if (raw === undefined || raw === null || raw === "") return null;
+  if (typeof raw === "number") {
+    if (!Number.isFinite(raw) || raw <= 0) return null;
+    return raw > 10_000_000_000 ? Math.floor(raw) : nowMs + Math.floor(raw * 1000);
+  }
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (!trimmed) return null;
+    const numeric = Number(trimmed);
+    if (Number.isFinite(numeric)) {
+      return parseExpiryMs(numeric, nowMs);
+    }
+    const parsed = Date.parse(trimmed);
+    return Number.isFinite(parsed) ? Math.floor(parsed) : null;
+  }
+  return null;
+}
+
+function normalizeSonioxTemporaryKeyResult(result, voiceSessionId, nowMs = Date.now()) {
+  const temporaryKey = pickTrimmedString(
+    result && result.temporaryKey,
+    result && result.temporary_key,
+    result && result.key,
+    result && result.apiKey,
+    result && result.api_key,
+  );
+  if (!temporaryKey) {
+    throw new Error("Soniox temporary-key response missing temporaryKey");
+  }
+
+  const expiresAtMs =
+    parseExpiryMs(
+      result && (
+        result.expiresAtMs ??
+        result.expires_at_ms ??
+        result.expiresAt ??
+        result.expires_at
+      ),
+      nowMs,
+    ) ??
+    (
+      Number.isFinite(result && result.expiresInSeconds)
+        ? nowMs + Math.floor(result.expiresInSeconds * 1000)
+        : null
+    ) ??
+    (
+      Number.isFinite(result && result.expires_in_seconds)
+        ? nowMs + Math.floor(result.expires_in_seconds * 1000)
+        : null
+    );
+
+  if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) {
+    throw new Error("Soniox temporary-key response missing expiresAtMs");
+  }
+
+  return {
+    voiceSessionId,
+    temporaryKey,
+    expiresAtMs: Math.floor(expiresAtMs),
+  };
+}
+
+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("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("temporary-key response missing")) {
+    return "soniox_temp_key_invalid_response";
+  }
+  if (lowered.includes("voicesessionid is required")) {
+    return "soniox_temp_key_invalid_request";
+  }
+  const statusMatch = lowered.match(/\((\d{3})\)/);
+  if (statusMatch) {
+    return `soniox_temp_key_http_${statusMatch[1]}`;
+  }
+  return "soniox_temp_key_request_failed";
+}
+
+function normalizeSonioxModelEntryRows(result) {
+  const rows =
+    result &&
+    typeof result === "object" &&
+    Array.isArray(result.models)
+      ? result.models
+      : [];
+  const models = [];
+  const seenIds = new Set();
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    const transcriptionMode =
+      typeof row.transcription_mode === "string"
+        ? row.transcription_mode.trim()
+        : "";
+    if (transcriptionMode !== "real_time") continue;
+    if (row.aliased_model_id !== undefined && row.aliased_model_id !== null) {
+      const aliasedModelId = pickTrimmedString(row.aliased_model_id);
+      if (aliasedModelId) continue;
+    }
+    const id = pickTrimmedString(row.id);
+    if (!id || seenIds.has(id)) continue;
+    seenIds.add(id);
+    models.push({
+      id,
+      name: pickTrimmedString(row.name) || id,
+      supportsMaxEndpointDelay: row.supports_max_endpoint_delay === true,
+    });
+  }
+  return models;
+}
+
+function createOwnedRelayHttpServer() {
+  return http.createServer((_req, res) => {
+    if (res.writableEnded || res[EVEN_AI_HANDLED]) {
+      return;
+    }
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain; charset=utf-8");
+    res.end("not found");
+  });
+}
+
+function listenOwnedRelayHttpServer(httpServer, host, port) {
+  if (!httpServer || httpServer.listening) {
+    return;
+  }
+  httpServer.listen(port, host);
+}
+
+function closeOwnedRelayHttpServer(httpServer) {
+  if (!httpServer || !httpServer.listening) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    httpServer.close(() => resolve());
+  });
+}
+
+// --- Factory ---
+
+/**
+ * Create the relay orchestrator.
+ *
+ * Wires the upstream gateway bridge to downstream clients via the
+ * conversation-state module, downstream handler, and downstream server.
+ * This is the only module that knows about both sides.
+ *
+ * @param {object} opts
+ * @param {number} opts.port - WebSocket server port
+ * @param {string} opts.host - WebSocket server bind address
+ * @param {string} opts.token - Authentication token for downstream clients
+ * @param {object} [opts.gatewayBridge] - Override bridge for testing/integration
+ * @param {object} [opts.openclawClient] - Override for testing (default: plugin gateway client)
+ * @param {object} [opts.conversationState] - Override for testing (default: require singleton)
+ * @param {object} [opts.logger] - Structured logger for shared runtime logs
+ * @param {string|null} [opts.consoleLogPath] - Optional shim-only browser console sink path
+ * @returns {object} Relay instance with start(), stop(), server
+ */
+function createRelay(opts) {
+  const logger = normalizeLogger(opts.logger);
+  const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
+  const openclawClient =
+    opts.openclawClient ||
+    (opts.gatewayBridge
+      ? null
+      : createPluginOpenclawClient({
+          gatewayUrl: opts.gatewayUrl,
+          gatewayToken: opts.gatewayToken,
+          logger,
+          stateDir: opts.stateDir,
+        }));
+  if (openclawClient && typeof openclawClient.setLogger === "function") {
+    openclawClient.setLogger(logger);
+  }
+  const gatewayBridge =
+    opts.gatewayBridge ||
+    createPluginRpcGatewayBridge({
+      openclawClient,
+    });
+  const conversationState =
+    opts.conversationState || conversationStateModule;
+  const activityStatusAdapter = createActivityStatusAdapter(
+    opts.activityStatusAdapter,
+  );
+  const ownedHttpServer =
+    !opts.httpServer && opts.evenAiEnabled === true ? createOwnedRelayHttpServer() : null;
+  const sharedHttpServer = opts.httpServer || ownedHttpServer || null;
+
+  // --- Cached state ---
+
+  /** @type {string|null} Last formatted pages JSON string. */
+  let cachedPages = null;
+  /** Monotonic pages snapshot revision used for resume handshake. */
+  let pagesRevision = 0;
+
+  /** @type {string|null} Last formatted status JSON string. */
+  let cachedStatus = null;
+  /** Monotonic status snapshot revision used for resume handshake. */
+  let statusRevision = 0;
+
+  /** Relay-local deterministic simulate-stream run sequence counter. */
+  let simulateStreamRunSeq = 0;
+  /** Active timers for relay-local deterministic simulate-stream runs. */
+  const simulateStreamTimers = new Set();
+
+  // --- Structured debug state ---
+
+  const debugStore = createDebugStore({
+    categories: opts.debugCategories,
+    capacity: opts.debugCapacity,
+    payloadMaxBytes: opts.debugPayloadMaxBytes,
+    defaultTtlMs: opts.debugDefaultTtlMs,
+    maxTtlMs: opts.debugMaxTtlMs,
+    dumpDefaultLimit: opts.debugDumpDefaultLimit,
+    dumpMaxLimit: opts.debugDumpMaxLimit,
+    now: opts.debugNow,
+    noisyPolicies: opts.debugNoisyPolicies,
+  });
+
+  // --- Console log file ---
+
+  const consoleLogPath =
+    typeof opts.consoleLogPath === "string" && opts.consoleLogPath.trim()
+      ? opts.consoleLogPath
+      : null;
+  // Clear the shim-only browser console sink on startup.
+  if (consoleLogPath) {
+    try {
+      fs.writeFileSync(consoleLogPath, "");
+    } catch {}
+  }
+  const CONSOLE_LOG_MAX_LINES = 500;
+  const CONSOLE_LOG_TRIM_TO = 250;
+
+  /**
+   * Append a browser console message to the log file.
+   * Trims the file when it exceeds CONSOLE_LOG_MAX_LINES.
+   *
+   * @param {string} level - "log", "warn", or "error"
+   * @param {string} message - Console message text
+   */
+  function writeConsoleLog(level, message) {
+    if (!consoleLogPath) {
+      logger.debug(`[browser:${level}] ${message}`);
+      return;
+    }
+    const timestamp = new Date().toISOString().replace("T", " ").slice(0, 19);
+    const line = `[${timestamp}] [${level}] ${message}\n`;
+    try {
+      fs.appendFileSync(consoleLogPath, line);
+      // Trim if too large
+      const content = fs.readFileSync(consoleLogPath, "utf8");
+      const lines = content.split("\n");
+      if (lines.length > CONSOLE_LOG_MAX_LINES) {
+        const trimmed = lines.slice(-CONSOLE_LOG_TRIM_TO).join("\n");
+        fs.writeFileSync(consoleLogPath, trimmed);
+      }
+    } catch (err) {
+      logger.error(`[relay] Console log write failed: ${err.message}`);
+    }
+  }
+
+  /**
+   * Emit a structured debug event when a category is enabled.
+   * This keeps the disabled path cheap by avoiding payload construction.
+   *
+   * @param {string} cat
+   * @param {string} event
+   * @param {"debug"|"info"|"warn"|"error"} severity
+   * @param {object} context
+   * @param {() => object} buildData
+   */
+  function emitDebug(cat, event, severity, context, buildData) {
+    if (!debugStore.isEnabled(cat)) return;
+
+    let data = {};
+    if (typeof buildData === "function") {
+      try {
+        data = buildData() || {};
+      } catch (err) {
+        data = { buildError: err.message || String(err) };
+      }
+    }
+
+    const payload = {
+      cat,
+      event,
+      severity,
+      data,
+    };
+
+    if (context && context.sessionKey) payload.sessionKey = context.sessionKey;
+    if (context && context.runId) payload.runId = context.runId;
+    if (context && context.screen) payload.screen = context.screen;
+
+    debugStore.emit(payload);
+  }
+
+  function scheduleSimulateStreamTimer(delayMs, callback) {
+    const timer = setTimeout(() => {
+      simulateStreamTimers.delete(timer);
+      try {
+        callback();
+      } catch (err) {
+        logger.error(`[relay] simulate-stream timer failed: ${err.message}`);
+      }
+    }, delayMs);
+    simulateStreamTimers.add(timer);
+    return timer;
+  }
+
+  function clearSimulateStreamTimers() {
+    for (const timer of simulateStreamTimers) {
+      clearTimeout(timer);
+    }
+    simulateStreamTimers.clear();
+  }
+
+  function resetActivityStatusAdapter() {
+    activityStatusAdapter.reset();
+  }
+
+  const configuredSonioxApiKey =
+    opts.sonioxApiKey !== undefined
+      ? opts.sonioxApiKey
+      : (opts.config && opts.config.sonioxApiKey) || "";
+  const sonioxTemporaryKeyExpiresInSeconds = Number.isFinite(
+    opts.sonioxTemporaryKeyExpiresInSeconds,
+  )
+    ? Math.max(30, Math.floor(opts.sonioxTemporaryKeyExpiresInSeconds))
+    : DEFAULT_SONIOX_TEMP_KEY_EXPIRES_IN_SECONDS;
+  /** @type {Array<{id: string, name: string, supportsMaxEndpointDelay: boolean}>|null} */
+  let cachedSonioxModels = null;
+  let cachedSonioxModelsFetchedAt = 0;
+  let cachedSonioxModelsStale = true;
+  let sonioxModelsFetchStarted = false;
+  /** @type {Promise<{models: Array, fetchedAtMs: number, stale: boolean}>|null} */
+  let inFlightSonioxModelsFetch = null;
+
+  function resolveFetchImpl() {
+    return typeof opts.fetch === "function"
+      ? opts.fetch
+      : typeof globalThis.fetch === "function"
+        ? globalThis.fetch.bind(globalThis)
+        : null;
+  }
+
+  function sonioxModelsSnapshot(nowMs) {
+    const now = Number.isFinite(nowMs) ? nowMs : Date.now();
+    const hasCache = Array.isArray(cachedSonioxModels);
+    return {
+      models: hasCache ? cachedSonioxModels : [],
+      fetchedAtMs: hasCache ? cachedSonioxModelsFetchedAt : now,
+      stale: !hasCache || cachedSonioxModelsStale,
+    };
+  }
+
+  function cacheSonioxModels(models, fetchedAtMs, stale) {
+    cachedSonioxModels = Array.isArray(models) ? models : [];
+    cachedSonioxModelsFetchedAt = Number.isFinite(fetchedAtMs)
+      ? Math.floor(fetchedAtMs)
+      : Date.now();
+    cachedSonioxModelsStale = !!stale;
+    return sonioxModelsSnapshot(cachedSonioxModelsFetchedAt);
+  }
+
+  function getSonioxModelsSnapshot() {
+    if (inFlightSonioxModelsFetch) {
+      return inFlightSonioxModelsFetch;
+    }
+    return Promise.resolve(sonioxModelsSnapshot());
+  }
+
+  function prefetchSonioxModels(trigger = "relay_start") {
+    if (inFlightSonioxModelsFetch) {
+      return inFlightSonioxModelsFetch;
+    }
+    if (sonioxModelsFetchStarted) {
+      return Promise.resolve(sonioxModelsSnapshot());
+    }
+    sonioxModelsFetchStarted = true;
+
+    const fetchImpl = resolveFetchImpl();
+    if (!configuredSonioxApiKey) {
+      const snapshot = cacheSonioxModels([], Date.now(), true);
+      emitDebug(
+        "voice.timeline",
+        "soniox_models_prefetch_skipped",
+        "warn",
+        { sessionKey: sessionService.peekSessionKey() || undefined },
+        () => ({
+          trigger,
+          reason: "api_key_not_configured",
+        }),
+      );
+      return Promise.resolve(snapshot);
+    }
+    if (!fetchImpl) {
+      const snapshot = cacheSonioxModels([], Date.now(), true);
+      emitDebug(
+        "voice.timeline",
+        "soniox_models_prefetch_skipped",
+        "warn",
+        { sessionKey: sessionService.peekSessionKey() || undefined },
+        () => ({
+          trigger,
+          reason: "fetch_unavailable",
+        }),
+      );
+      return Promise.resolve(snapshot);
+    }
+
+    inFlightSonioxModelsFetch = Promise.resolve()
+      .then(async () => {
+        const response = await fetchImpl(SONIOX_MODELS_URL, {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${configuredSonioxApiKey}`,
+          },
+        });
+        const rawText =
+          response && typeof response.text === "function"
+            ? await response.text()
+            : "";
+        let payload = {};
+        if (rawText) {
+          try {
+            payload = JSON.parse(rawText);
+          } catch {
+            if (!response.ok) {
+              throw new Error(
+                `Soniox models request failed (${response.status}): ${tailForLog(rawText)}`,
+              );
+            }
+            throw new Error(
+              `Soniox models response was not valid JSON (${response.status})`,
+            );
+          }
+        }
+        if (!response.ok) {
+          const errorDetail = pickTrimmedString(
+            payload && payload.error,
+            payload && payload.message,
+            payload && payload.detail,
+            rawText,
+          ) || `HTTP ${response.status}`;
+          throw new Error(
+            `Soniox models request failed (${response.status}): ${tailForLog(errorDetail)}`,
+          );
+        }
+        const snapshot = cacheSonioxModels(
+          normalizeSonioxModelEntryRows(payload || {}),
+          Date.now(),
+          false,
+        );
+        emitDebug(
+          "voice.timeline",
+          "soniox_models_prefetched",
+          "info",
+          { sessionKey: sessionService.peekSessionKey() || undefined },
+          () => ({
+            trigger,
+            count: snapshot.models.length,
+            stale: snapshot.stale,
+          }),
+        );
+        return snapshot;
+      })
+      .catch((err) => {
+        const snapshot = Array.isArray(cachedSonioxModels)
+          ? cacheSonioxModels(cachedSonioxModels, cachedSonioxModelsFetchedAt, true)
+          : cacheSonioxModels([], Date.now(), true);
+        emitDebug(
+          "voice.timeline",
+          "soniox_models_prefetch_failed",
+          "warn",
+          { sessionKey: sessionService.peekSessionKey() || undefined },
+          () => ({
+            trigger,
+            message: err && err.message ? err.message : String(err),
+          }),
+        );
+        return snapshot;
+      })
+      .finally(() => {
+        inFlightSonioxModelsFetch = null;
+      });
+
+    return inFlightSonioxModelsFetch;
+  }
+
+  async function mintSonioxTemporaryKey(clientId, request) {
+    const voiceSessionId = pickTrimmedString(request && request.voiceSessionId);
+    if (!voiceSessionId) {
+      throw new Error("voiceSessionId is required");
+    }
+
+    const sessionKey = pickTrimmedString(request && request.sessionKey) || null;
+    const nowMs = Date.now();
+    const resolvedSessionKey = sessionKey || sessionService.peekSessionKey() || undefined;
+    const emitIssued = (normalized, source) => {
+      logger.info(
+        `[relay] soniox temp key issued: clientId=${clientId} voiceSessionId=${voiceSessionId} source=${source} expiresAtMs=${normalized.expiresAtMs}`,
+      );
+      emitDebug(
+        "voice.timeline",
+        "soniox_temp_key_issued",
+        "info",
+        { sessionKey: resolvedSessionKey },
+        () => ({
+          clientId,
+          voiceSessionId,
+          expiresAtMs: normalized.expiresAtMs,
+          source,
+        }),
+      );
+      return normalized;
+    };
+
+    try {
+      emitDebug(
+        "voice.timeline",
+        "soniox_temp_key_requested",
+        "info",
+        { sessionKey: resolvedSessionKey },
+        () => ({
+          clientId,
+          voiceSessionId,
+          expiresInSeconds: sonioxTemporaryKeyExpiresInSeconds,
+        }),
+      );
+
+      if (typeof opts.createSonioxTemporaryKey === "function") {
+        const overrideResult = await Promise.resolve(
+          opts.createSonioxTemporaryKey({
+            voiceSessionId,
+            sessionKey,
+            expiresInSeconds: sonioxTemporaryKeyExpiresInSeconds,
+          }),
+        );
+        return emitIssued(
+          normalizeSonioxTemporaryKeyResult(
+            overrideResult || {},
+            voiceSessionId,
+            nowMs,
+          ),
+          "override",
+        );
+      }
+
+      if (!configuredSonioxApiKey) {
+        throw new Error("Soniox API key is not configured");
+      }
+
+      const fetchImpl = resolveFetchImpl();
+      if (!fetchImpl) {
+        throw new Error("fetch is not available for Soniox temporary-key minting");
+      }
+
+      const response = await fetchImpl(SONIOX_TEMP_KEY_URL, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${configuredSonioxApiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          usage_type: "transcribe_websocket",
+          expires_in_seconds: sonioxTemporaryKeyExpiresInSeconds,
+          client_reference_id: voiceSessionId,
+        }),
+      });
+
+      const rawText =
+        response && typeof response.text === "function"
+          ? await response.text()
+          : "";
+      let payload = {};
+      if (rawText) {
+        try {
+          payload = JSON.parse(rawText);
+        } catch (err) {
+          if (!response.ok) {
+            throw new Error(
+              `Soniox temporary-key request failed (${response.status}): ${tailForLog(rawText)}`,
+            );
+          }
+          throw new Error(
+            `Soniox temporary-key response was not valid JSON (${response.status})`,
+          );
+        }
+      }
+
+      if (!response.ok) {
+        const errorDetail = pickTrimmedString(
+          payload && payload.error,
+          payload && payload.message,
+          payload && payload.detail,
+          rawText,
+        ) || `HTTP ${response.status}`;
+        throw new Error(
+          `Soniox temporary-key request failed (${response.status}): ${tailForLog(errorDetail)}`,
+        );
+      }
+
+      return emitIssued(
+        normalizeSonioxTemporaryKeyResult(
+          payload || {},
+          voiceSessionId,
+          nowMs,
+        ),
+        "soniox_api",
+      );
+    } catch (err) {
+      const message =
+        err && err.message
+          ? err.message
+          : "Soniox temporary-key request failed";
+      const code = normalizeSonioxTemporaryKeyErrorCode(err);
+      logger.warn(
+        `[relay] soniox temp key failed: clientId=${clientId} voiceSessionId=${voiceSessionId} code=${code} message=${tailForLog(message)}`,
+      );
+      emitDebug(
+        "voice.timeline",
+        "soniox_temp_key_failed",
+        "warn",
+        { sessionKey: resolvedSessionKey },
+        () => ({
+          clientId,
+          voiceSessionId,
+          code,
+          message: tailForLog(message),
+        }),
+      );
+      throw err;
+    }
+  }
+
+  let upstreamRuntime = null;
+  const evenAiSettingsStore = createEvenAiSettingsStore({
+    logger,
+    emitDebug,
+    stateDir: opts.stateDir,
+    defaults: {
+      routingMode: opts.evenAiRoutingMode,
+      systemPrompt: opts.evenAiSystemPrompt,
+    },
+  });
+  const ocuClawSettingsStore = createOcuClawSettingsStore({
+    logger,
+    emitDebug,
+    stateDir: opts.stateDir,
+    defaults: {
+      systemPrompt: opts.ocuClawSystemPrompt,
+    },
+  });
+
+  function currentOcuClawSendOptions() {
+    return {
+      extraSystemPrompt: composeReadabilitySystemPrompt(
+        ocuClawSettingsStore.getSnapshot().systemPrompt,
+      ),
+    };
+  }
+
+  function buildLocalUserMessageContent(text, attachment) {
+    const userContent = [];
+    if (typeof text === "string" && text.trim()) {
+      userContent.push({ type: "text", text });
+    }
+    if (attachment) {
+      userContent.push({
+        type: "image",
+        mimeType: attachment.mimeType || null,
+        fileName: attachment.name || null,
+        source: attachment.source || null,
+        sizeBytes:
+          Number.isFinite(attachment.sizeBytes) && attachment.sizeBytes > 0
+            ? Math.floor(attachment.sizeBytes)
+            : null,
+        widthPx:
+          Number.isFinite(attachment.widthPx) && attachment.widthPx > 0
+            ? Math.floor(attachment.widthPx)
+            : null,
+        heightPx:
+          Number.isFinite(attachment.heightPx) && attachment.heightPx > 0
+            ? Math.floor(attachment.heightPx)
+            : null,
+      });
+    }
+    if (userContent.length === 0) {
+      userContent.push({ type: "text", text });
+    }
+    return userContent;
+  }
+
+  function buildOcuClawInitialSessionConfigPatch(settings) {
+    const patch = {};
+    if (settings && typeof settings.defaultModel === "string" && settings.defaultModel.trim()) {
+      patch.modelRef = settings.defaultModel.trim();
+    }
+    if (
+      settings &&
+      typeof settings.defaultThinking === "string" &&
+      settings.defaultThinking.trim()
+    ) {
+      patch.thinkingLevel = settings.defaultThinking.trim().toLowerCase();
+    }
+    return Object.keys(patch).length > 0 ? patch : null;
+  }
+
+  async function maybeSeedOcuClawSessionConfig(sessionKey) {
+    if (
+      !sessionKey ||
+      !sessionService ||
+      typeof sessionService.hasPendingInitialConfig !== "function" ||
+      !sessionService.hasPendingInitialConfig(sessionKey)
+    ) {
+      return;
+    }
+
+    const settings = ocuClawSettingsStore.getSnapshot();
+    const patch = buildOcuClawInitialSessionConfigPatch(settings);
+    if (!patch) {
+      sessionService.clearPendingInitialConfig(sessionKey);
+      return;
+    }
+
+    const result = await sessionService.setSessionModelConfig(sessionKey, patch);
+    if (!result || result.status !== "accepted") {
+      throw new Error(
+        (result && result.error) || "failed to seed OcuClaw new-session defaults",
+      );
+    }
+    if (
+      result.config &&
+      sessionKey === sessionService.ensureSessionKey() &&
+      server
+    ) {
+      server.broadcast(handler.formatSessionModelConfig(result.config));
+    }
+  }
+
+  async function seedOcuClawSessionConfigForNewSession(sessionKey) {
+    if (!sessionKey || !sessionService) {
+      return null;
+    }
+
+    const settings = ocuClawSettingsStore.getSnapshot();
+    const patch = buildOcuClawInitialSessionConfigPatch(settings);
+    if (!patch) {
+      return null;
+    }
+
+    const seededConfig =
+      typeof sessionService.primeSessionModelConfig === "function"
+        ? sessionService.primeSessionModelConfig(sessionKey, patch)
+        : null;
+    const result = await sessionService.setSessionModelConfig(sessionKey, patch);
+    if (result && result.status === "accepted" && result.config) {
+      return result.config;
+    }
+    return seededConfig;
+  }
+
+  const sessionService = createSessionService({
+    logger,
+    gatewayBridge,
+    conversationState,
+    emitDebug,
+    stateDir: opts.stateDir,
+    sessionLimit: opts.sessionLimit,
+    persistFirstUserMessages: opts.persistFirstUserMessages,
+    strictFirstUserMessage: opts.strictFirstUserMessage,
+    sessionCacheTtlMs: opts.sessionCacheTtlMs,
+    getOpenclawConnected() {
+      return upstreamRuntime ? upstreamRuntime.isConnected() : false;
+    },
+    getAgentName() {
+      return upstreamRuntime ? upstreamRuntime.getAgentName() : null;
+    },
+    onSessionStateReset: resetActivityStatusAdapter,
+    onPagesChanged: cachePages,
+    onStatusChanged: broadcastStatus,
+  });
+
+  function broadcastActivity(rawActivity) {
+    const activity = activityStatusAdapter.augmentActivity(rawActivity || {});
+    const runId = activity && activity.runId ? activity.runId : null;
+    const origin = activity && activity.origin ? activity.origin : null;
+    const phase = activity && activity.phase ? activity.phase : null;
+
+    emitDebug(
+      "app.timeline",
+      "activity",
+      "debug",
+      {
+        sessionKey: (activity && activity.sessionKey) || sessionService.ensureSessionKey(),
+        runId,
+      },
+      () => ({
+        state: (activity && activity.state) || null,
+        tool: (activity && activity.tool) || null,
+        label: (activity && activity.label) || null,
+        intent: (activity && activity.intent) || null,
+        thinkingSummarySource: (activity && activity.thinkingSummarySource) || null,
+        category: (activity && activity.category) || null,
+        activityId: (activity && activity.activityId) || null,
+        seq: Number.isFinite(activity && activity.seq) ? activity.seq : null,
+        origin,
+        phase,
+      }),
+    );
+
+    server.broadcast(handler.formatActivity(activity));
+    return activity;
+  }
+
+  function normalizeAttachmentErrorCode(err) {
+    if (!err) return "attachment_upstream_rejected";
+    const code = typeof err.code === "string" ? err.code.trim() : "";
+    if (
+      code === "attachment_invalid_type" ||
+      code === "attachment_decode_failed" ||
+      code === "attachment_too_large" ||
+      code === "attachment_too_large_encoded" ||
+      code === "attachment_missing_data" ||
+      code === "attachment_upstream_rejected"
+    ) {
+      return code;
+    }
+
+    const message = typeof err.message === "string" ? err.message.toLowerCase() : "";
+    if (message.includes("invalid type") || message.includes("mime")) {
+      return "attachment_invalid_type";
+    }
+    if (message.includes("base64") || message.includes("decode")) {
+      return "attachment_decode_failed";
+    }
+    if (message.includes("too large") || message.includes("exceeds")) {
+      return "attachment_too_large";
+    }
+    return "attachment_upstream_rejected";
+  }
+
+  function dispatchOcuClawUserSend(params = {}) {
+    const id = params.id;
+    const text = params.text;
+    const sessionKey = params.sessionKey;
+    const attachment = params.attachment || null;
+    const resolvedSessionKey = sessionKey || sessionService.ensureSessionKey();
+    sessionService.recordFirstSentUserMessage(resolvedSessionKey, text);
+    const hasAttachment = !!attachment;
+    const sendStartedAt = Date.now();
+    sessionService.invalidateSessionsCache();
+    emitDebug(
+      "relay.protocol",
+      "send",
+      "info",
+      { sessionKey: resolvedSessionKey },
+      () => ({
+        messageId: id,
+        textChars: typeof text === "string" ? text.length : 0,
+        hasAttachment,
+        attachmentBytes:
+          attachment && Number.isFinite(attachment.sizeBytes)
+            ? attachment.sizeBytes
+            : null,
+      }),
+    );
+
+    return maybeSeedOcuClawSessionConfig(resolvedSessionKey).then(() => {
+      // Dispatch upstream first so local transcript work cannot delay first
+      // model tokens on large histories.
+      const upstreamPromise = gatewayBridge.sendMessage(
+        text,
+        resolvedSessionKey,
+        attachment,
+        currentOcuClawSendOptions(),
+      );
+      const upstreamDispatchedAt = Date.now();
+
+      conversationState.addMessage(
+        "user",
+        buildLocalUserMessageContent(text, attachment),
+      );
+      broadcastPages();
+      const localPublishDoneAt = Date.now();
+
+      emitDebug(
+        "relay.protocol",
+        "send_local_publish",
+        "debug",
+        { sessionKey: resolvedSessionKey },
+        () => ({
+          messageId: id,
+          upstreamDispatchMs: upstreamDispatchedAt - sendStartedAt,
+          localPublishMs: localPublishDoneAt - upstreamDispatchedAt,
+          onSendSyncMs: localPublishDoneAt - sendStartedAt,
+          hasAttachment,
+        }),
+      );
+
+      return upstreamPromise.then(
+        (result) => {
+          const ackAt = Date.now();
+          const runId = result && result.runId ? result.runId : null;
+          if (runId && upstreamRuntime) {
+            upstreamRuntime.trackAcceptedRun({
+              runId,
+              sessionKey: resolvedSessionKey,
+              messageId: id,
+              sendStartedAt,
+              ackAt,
+            });
+          }
+          emitDebug(
+            "relay.protocol",
+            "send_upstream_ack",
+            "debug",
+            { sessionKey: resolvedSessionKey, runId },
+            () => ({
+              messageId: id,
+              runId,
+              status: result && result.status ? result.status : null,
+              elapsedMs: ackAt - sendStartedAt,
+              hasAttachment,
+            }),
+          );
+          return result;
+        },
+        (err) => {
+          if (attachment && !err.errorCode) {
+            err.errorCode = normalizeAttachmentErrorCode(err);
+          }
+          emitDebug(
+            "relay.protocol",
+            "send_upstream_error",
+            "warn",
+            { sessionKey: resolvedSessionKey },
+            () => ({
+              messageId: id,
+              elapsedMs: Date.now() - sendStartedAt,
+              hasAttachment,
+              errorCode: err.errorCode || null,
+              message: err && err.message ? err.message : String(err),
+            }),
+          );
+          throw err;
+        },
+      );
+    });
+  }
+
+  function emitListenInterceptRecovery(params = {}) {
+    const connectedAppClients = server ? server.getConnectedAppCount() : 0;
+    if (!server || !handler) {
+      return {
+        cleanupEmitted: false,
+        connectedAppClients,
+      };
+    }
+
+    server.broadcast(
+      handler.formatListenError(
+        LISTEN_INTERCEPT_RECOVERY_ERROR,
+        LISTEN_INTERCEPT_RECOVERY_CODE,
+      ),
+    );
+    server.broadcast(handler.formatListenEnded());
+    return {
+      cleanupEmitted: true,
+      connectedAppClients,
+    };
+  }
+
+  // --- Downstream handler ---
+
+  /** @type {ReturnType<typeof createDownstreamServer>|null} */
+  let server = null;
+  let evenAiEndpoint = null;
+  let evenAiRouter = null;
+  let evenAiRunWaiter = null;
+
+  const handler = createDownstreamHandler({
+    logger,
+    externalDebugToolsEnabled,
+    getSnapshotRevision(kind) {
+      if (kind === "pages") return pagesRevision;
+      if (kind === "status") return statusRevision;
+      return null;
+    },
+    /**
+     * Forward a user message to the upstream OpenClaw agent.
+     *
+     * @param {string} id - Message ID
+     * @param {string} text - User message text
+     * @param {string|null} sessionKey - Session key
+     * @param {object|null} attachment - Optional image attachment payload
+     * @returns {Promise}
+     */
+    onSend(id, text, sessionKey, attachment) {
+      return dispatchOcuClawUserSend({
+        id,
+        text,
+        sessionKey,
+        attachment,
+      });
+    },
+
+    /**
+     * Inject a fake assistant message into conversation state.
+     *
+     * The sender name is used as a temporary agent name prefix for
+     * this message. If no agent identity has been established yet,
+     * the sender becomes the default agent name going forward.
+     *
+     * @param {string} sender - Display name for the simulated message
+     * @param {string} text - Message text
+     * @returns {Array<{content: string, subPage: [number, number]|null}>}
+     */
+    onSimulate(sender, text) {
+      emitDebug(
+        "relay.protocol",
+        "simulate",
+        "debug",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          sender: sender || "Simulator",
+          textChars: typeof text === "string" ? text.length : 0,
+        }),
+      );
+      // Add with per-message name override (doesn't affect other messages' prefix)
+      conversationState.addMessage("assistant", [{ type: "text", text }], sender || "Simulator");
+
+      const pages = conversationState.getPages();
+      cachePages(pages);
+      return pages;
+    },
+
+    onSimulateStream(request) {
+      const sessionKey = request.sessionKey || sessionService.ensureSessionKey();
+      const sender = (
+        request.sender ||
+        (upstreamRuntime ? upstreamRuntime.getAgentName() : null) ||
+        "Simulator"
+      ).trim();
+      const text = typeof request.text === "string" ? request.text : "";
+      const chunkChars = Math.min(
+        200,
+        Math.max(1, request.chunkChars || 16),
+      );
+      const chunkIntervalMs = Math.min(
+        5000,
+        Math.max(10, request.chunkIntervalMs || 45),
+      );
+      const startDelayMs = Math.min(
+        5000,
+        Math.max(0, request.startDelayMs || 80),
+      );
+      const thinkingTailMs = Math.min(
+        10000,
+        Math.max(0, request.thinkingTailMs || 900),
+      );
+      const runId = `sim-${Date.now()}-${++simulateStreamRunSeq}`;
+      const chunkCount = Math.max(1, Math.ceil(text.length / chunkChars));
+      const streamPrefix = `${sender}: `;
+
+      emitDebug(
+        "relay.protocol",
+        "simulate_stream_start",
+        "info",
+        { sessionKey, runId },
+        () => ({
+          messageId: request.id || null,
+          sender,
+          textChars: text.length,
+          chunkChars,
+          chunkIntervalMs,
+          startDelayMs,
+          thinkingTailMs,
+          chunkCount,
+        }),
+      );
+
+      broadcastActivity({
+        state: "thinking",
+        sessionKey,
+        runId,
+        origin: "simulate",
+        phase: "start",
+      });
+
+      for (let index = 0; index < chunkCount; index += 1) {
+        const visibleChars = Math.min(text.length, (index + 1) * chunkChars);
+        const delayMs = startDelayMs + (index * chunkIntervalMs);
+        scheduleSimulateStreamTimer(delayMs, () => {
+          const streamedText = `${streamPrefix}${text.slice(0, visibleChars)}`;
+          server.broadcast(handler.formatStreaming(streamedText));
+          emitDebug(
+            "relay.protocol",
+            "simulate_stream_chunk",
+            "debug",
+            { sessionKey, runId },
+            () => ({
+              chunkIndex: index + 1,
+              chunkCount,
+              visibleChars,
+              totalChars: text.length,
+            }),
+          );
+        });
+      }
+
+      const completeDelayMs = startDelayMs + (chunkCount * chunkIntervalMs) + thinkingTailMs;
+      scheduleSimulateStreamTimer(completeDelayMs, () => {
+        conversationState.addMessage(
+          "assistant",
+          [{ type: "text", text }],
+          sender,
+        );
+        broadcastPages();
+        broadcastActivity({
+          state: "idle",
+          sessionKey,
+          runId,
+          origin: "simulate",
+          phase: "complete",
+        });
+        emitDebug(
+          "relay.protocol",
+          "simulate_stream_complete",
+          "info",
+          { sessionKey, runId },
+          () => ({
+            messageId: request.id || null,
+            textChars: text.length,
+            chunkCount,
+            thinkingTailMs,
+            completeDelayMs,
+          }),
+        );
+      });
+
+      return Promise.resolve({
+        status: "accepted",
+        runId,
+      });
+    },
+
+    /**
+     * Clear conversation state, reset cached pages, and send /new to OpenClaw.
+     * Legacy support: delegates to newSession.
+     *
+     * @returns {Promise<Array>} Empty pages array
+     */
+    onNewChat() {
+      emitDebug(
+        "relay.session",
+        "new_chat",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({}),
+      );
+      sessionService.invalidateSessionsCache();
+      resetActivityStatusAdapter();
+      conversationState.clear();
+      conversationState.setAgentName(
+        (upstreamRuntime ? upstreamRuntime.getAgentName() : null) || "Agent",
+      );
+      const pages = conversationState.getPages();
+      cachePages(pages);
+      if (upstreamRuntime && upstreamRuntime.isConnected()) {
+        gatewayBridge.sendMessage("/new", "main").catch((err) => {
+          logger.error(`[relay] Failed to send /new: ${err.message}`);
+        });
+      }
+      return Promise.resolve(pages);
+    },
+
+    onGetSessions() {
+      return sessionService.getSessions();
+    },
+
+    onSwitchSession(sessionKey) {
+      return sessionService.switchToSession(sessionKey).then((pages) => {
+        if (upstreamRuntime && typeof upstreamRuntime.handleSessionChanged === "function") {
+          upstreamRuntime.handleSessionChanged("switch_session");
+        }
+        return pages;
+      });
+    },
+
+    async onNewSession() {
+      const result = await sessionService.newSession();
+      if (upstreamRuntime && typeof upstreamRuntime.handleSessionChanged === "function") {
+        upstreamRuntime.handleSessionChanged("new_session");
+      }
+      const sessionModelConfig = await seedOcuClawSessionConfigForNewSession(
+        result && result.sessionKey,
+      );
+      return sessionModelConfig
+        ? {
+            ...result,
+            sessionModelConfig,
+          }
+        : result;
+    },
+
+    onGetModelsCatalog() {
+      return upstreamRuntime
+        ? upstreamRuntime.getModelsCatalogSnapshot()
+        : Promise.resolve({ models: [], fetchedAtMs: Date.now(), stale: true });
+    },
+
+    onGetSkillsCatalog() {
+      return upstreamRuntime
+        ? upstreamRuntime.getSkillsCatalogSnapshot()
+        : Promise.resolve({ skills: [], fetchedAtMs: Date.now(), stale: true });
+    },
+
+    onGetSonioxModels() {
+      return getSonioxModelsSnapshot();
+    },
+
+    onGetStatus() {
+      return buildStatusObject();
+    },
+
+    onGetSessionModelConfig() {
+      return sessionService.getCurrentSessionModelConfig();
+    },
+
+    async onSetSessionModelConfig(patch) {
+      const result = await sessionService.setCurrentSessionModelConfig(patch || {});
+      if (result && result.status === "accepted" && result.config) {
+        server.broadcast(handler.formatSessionModelConfig(result.config));
+      }
+      return result;
+    },
+
+    onGetEvenAiSettings() {
+      return evenAiSettingsStore.getSnapshot();
+    },
+
+    onGetOcuClawSettings() {
+      return ocuClawSettingsStore.getSnapshot();
+    },
+
+    async onGetEvenAiSessions() {
+      const dedicatedKey =
+        evenAiRouter && typeof evenAiRouter.getDedicatedSessionKey === "function"
+          ? evenAiRouter.getDedicatedSessionKey()
+          : opts.evenAiDedicatedSessionKey;
+      const dedicatedEvenAiKey = normalizeEvenAiSessionKeyForLookup(dedicatedKey);
+      const trackedThrowawayKeys =
+        typeof evenAiSettingsStore.getTrackedThrowawayKeys === "function"
+          ? evenAiSettingsStore.getTrackedThrowawayKeys()
+          : [];
+      const normalizedTrackedThrowawayKeys = dedupeNormalizedSessionKeys(
+        trackedThrowawayKeys,
+      );
+      const resolvedSessions = await sessionService.getSessionsByExactKeys([
+        ...normalizedTrackedThrowawayKeys,
+        ...(dedicatedEvenAiKey ? [dedicatedEvenAiKey] : []),
+      ]);
+      const normalizedDedicatedKey = dedicatedEvenAiKey.toLowerCase();
+      const sessions = [];
+      let dedicatedIncluded = false;
+      for (const session of resolvedSessions) {
+        if (
+          !dedicatedIncluded &&
+          session &&
+          typeof session.key === "string" &&
+          session.key.trim().toLowerCase() === normalizedDedicatedKey
+        ) {
+          sessions.push(session);
+          dedicatedIncluded = true;
+          continue;
+        }
+        sessions.push(session);
+      }
+      if (!dedicatedIncluded && dedicatedEvenAiKey) {
+        sessions.unshift({
+          key: dedicatedEvenAiKey,
+          updatedAt: 0,
+          preview: "",
+          firstUserMessage: "",
+        });
+      }
+      return {
+        sessions,
+        dedicatedKey,
+      };
+    },
+
+    async onSetEvenAiSettings(patch) {
+      const result = await evenAiSettingsStore.setSettings(patch || {});
+      if (result && result.status === "accepted" && result.settings && server) {
+        server.broadcast(handler.formatEvenAiSettings(result.settings));
+      }
+      return result;
+    },
+
+    async onSetOcuClawSettings(patch) {
+      const result = await ocuClawSettingsStore.setSettings(patch || {});
+      if (result && result.status === "accepted" && result.settings && server) {
+        server.broadcast(handler.formatOcuClawSettings(result.settings));
+      }
+      return result;
+    },
+
+    onSlashCommand(command) {
+      emitDebug(
+        "relay.protocol",
+        "slash_command",
+        "debug",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({ command }),
+      );
+      if (command === "/reset") {
+        sessionService.invalidateSessionsCache();
+        resetActivityStatusAdapter();
+        conversationState.clear();
+        conversationState.setAgentName(
+          (upstreamRuntime ? upstreamRuntime.getAgentName() : null) || "Agent",
+        );
+        broadcastPages();
+      }
+      if (upstreamRuntime && upstreamRuntime.isConnected()) {
+        return gatewayBridge.sendMessage(command, sessionService.ensureSessionKey());
+      }
+      return Promise.resolve();
+    },
+
+    /**
+     * @returns {boolean} Whether upstream is connected.
+     */
+    isUpstreamConnected() {
+      return upstreamRuntime ? upstreamRuntime.isConnected() : false;
+    },
+
+    onConsoleLog(level, message) {
+      writeConsoleLog(level, message);
+      if (level === "event") {
+        emitDebug(
+          "sdk.events",
+          "event_debug",
+          "debug",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            level,
+            message,
+          }),
+        );
+      }
+    },
+
+    onEventDebug(clientId, payload) {
+      if (!payload || typeof payload !== "object") return;
+      const cat = payload.cat;
+      if (!debugStore.isEnabled(cat)) return;
+      emitDebug(
+        cat,
+        payload.event,
+        payload.severity || "debug",
+        {
+          sessionKey: payload.sessionKey || sessionService.ensureSessionKey(),
+          runId: payload.runId || null,
+          screen: payload.screen || null,
+        },
+        () => ({
+          clientId,
+          ...(payload.data || {}),
+        }),
+      );
+    },
+
+    onApprovalResolve(id, decision) {
+      return gatewayBridge.resolveApproval(id, decision);
+    },
+
+    onRequestSonioxTemporaryKey(clientId, request) {
+      return mintSonioxTemporaryKey(clientId, request);
+    },
+
+    onDebugSet(clientId, request) {
+      const result = debugStore.setCategories(request);
+      if (!result.ok) {
+        throw new Error(result.error || "debug-set failed");
+      }
+
+      emitDebug(
+        "relay.protocol",
+        "debug_set",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          enable: result.applied.enable,
+          disable: result.applied.disable,
+          ttlMs: result.ttlMs,
+          enabledCount: result.enabled.length,
+        }),
+      );
+
+      return result;
+    },
+
+    onDebugDump(clientId, request) {
+      const result = debugStore.dump(request);
+      if (!result.ok) {
+        throw new Error(result.error || "debug-dump failed");
+      }
+
+      emitDebug(
+        "relay.protocol",
+        "debug_dump",
+        "debug",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          categories: result.categories,
+          redaction: result.redaction,
+          limit: result.limit,
+          returned: result.returned,
+          totalMatched: result.totalMatched,
+        }),
+      );
+
+      return result;
+    },
+
+    onRemoteControl(clientId, request) {
+      const now = Date.now();
+      const requestId =
+        (typeof request.requestId === "string" && request.requestId.trim()) ||
+        `rc-${now}-${Math.random().toString(16).slice(2, 8)}`;
+      const isDebugCloseAppClientAction =
+        request &&
+        request.action === "relay-action" &&
+        request.relayAction === "debug-close-app-client";
+      const recipientEstimate = server ? server.getConnectedAppCount(clientId) : 0;
+
+      emitDebug(
+        "relay.protocol",
+        "remote_control_requested",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          action: request.action || "unknown",
+          recipientEstimate,
+        }),
+      );
+
+      if (recipientEstimate <= 0) {
+        return {
+          ok: false,
+          requestId,
+          message: "No downstream app clients connected",
+          detail: { recipientEstimate },
+        };
+      }
+
+      if (isDebugCloseAppClientAction) {
+        if (!server || typeof server.closeConnectedAppClients !== "function") {
+          return {
+            ok: false,
+            requestId,
+            message: "Downstream close hook unavailable",
+            detail: { recipientEstimate },
+          };
+        }
+        const closeResult = server.closeConnectedAppClients({
+          excludeClientId: clientId,
+          reason: "debug_close_app_client",
+        });
+        emitDebug(
+          "relay.protocol",
+          "remote_control_server_action_applied",
+          "warn",
+          { sessionKey: sessionService.ensureSessionKey() },
+          () => ({
+            clientId,
+            requestId,
+            action: request.action || "unknown",
+            relayAction: request.relayAction || null,
+            recipientEstimate,
+            closedCount: closeResult.closedCount,
+            closedClientIds: closeResult.closedClientIds,
+            reason: closeResult.reason,
+          }),
+        );
+        return {
+          ok: closeResult.closedCount > 0,
+          requestId,
+          message:
+            closeResult.closedCount > 0
+              ? `Closed ${closeResult.closedCount} app client(s)`
+              : "No downstream app clients connected",
+          detail: {
+            recipientEstimate,
+            closedCount: closeResult.closedCount,
+            closedClientIds: closeResult.closedClientIds,
+            reason: closeResult.reason,
+          },
+        };
+      }
+
+      const control = {
+        ...request,
+        requestId,
+        issuedAtMs: now,
+        issuedByClientId: clientId,
+      };
+
+      emitDebug(
+        "relay.protocol",
+        "remote_control_dispatched",
+        "info",
+        { sessionKey: sessionService.ensureSessionKey() },
+        () => ({
+          clientId,
+          requestId,
+          action: control.action || "unknown",
+          recipientEstimate,
+        }),
+      );
+
+      return {
+        ok: true,
+        requestId,
+        message: `Dispatched to ${recipientEstimate} client(s)`,
+        detail: { recipientEstimate },
+        control,
+      };
+    },
+  });
+
+  // --- Downstream server ---
+
+  server = createDownstreamServer({
+    logger,
+    externalDebugToolsEnabled,
+    handler,
+    getCurrentPages() {
+      return cachedPages;
+    },
+    getCurrentStatus() {
+      return cachedStatus;
+    },
+    getCurrentDebugConfig() {
+      return handler.formatDebugConfigSnapshot(debugStore.getSnapshot());
+    },
+    getCurrentResumeState() {
+      return {
+        pagesRevision: pagesRevision || 0,
+        statusRevision: statusRevision || 0,
+      };
+    },
+    onClientConnected(meta) {
+      emitDebug(
+        "relay.session",
+        "downstream_client_connected",
+        "info",
+        { sessionKey: sessionService.peekSessionKey() || undefined },
+        () => ({
+          clientId: meta && meta.clientId ? meta.clientId : null,
+          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
+          connectedAtMs: meta && Number.isFinite(meta.connectedAtMs) ? meta.connectedAtMs : null,
+          remoteAddress: meta && meta.remoteAddress ? meta.remoteAddress : null,
+          userAgentTail: meta && meta.userAgent ? meta.userAgent : null,
+        }),
+      );
+    },
+    onClientDisconnected(meta) {
+      emitDebug(
+        "relay.session",
+        "downstream_client_disconnected",
+        "info",
+        { sessionKey: sessionService.peekSessionKey() || undefined },
+        () => ({
+          clientId: meta && meta.clientId ? meta.clientId : null,
+          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
+          connectedAtMs: meta && Number.isFinite(meta.connectedAtMs) ? meta.connectedAtMs : null,
+          lifetimeMs: meta && Number.isFinite(meta.lifetimeMs) ? meta.lifetimeMs : null,
+          closeCode: meta && Number.isFinite(meta.closeCode) ? meta.closeCode : null,
+          closeReasonTail: meta && meta.closeReason ? meta.closeReason : null,
+          role: meta && meta.role ? meta.role : null,
+          clientKind: meta && meta.clientKind ? meta.clientKind : null,
+          protocolVersion: meta && meta.protocolVersion ? meta.protocolVersion : null,
+          protocolReason: meta && meta.protocolReason ? meta.protocolReason : null,
+          clientName: meta && meta.clientName ? meta.clientName : null,
+          clientVersion: meta && meta.clientVersion ? meta.clientVersion : null,
+          firstMessageType: meta && meta.firstMessageType ? meta.firstMessageType : null,
+          textMessageCount: meta && Number.isFinite(meta.textMessageCount) ? meta.textMessageCount : null,
+          binaryMessageCount: meta && Number.isFinite(meta.binaryMessageCount) ? meta.binaryMessageCount : null,
+          remoteControlCount: meta && Number.isFinite(meta.remoteControlCount) ? meta.remoteControlCount : null,
+        }),
+      );
+    },
+    onTransportControl(meta) {
+      if (!meta || meta.controlType !== "visibility") {
+        return;
+      }
+      emitDebug(
+        "relay.session",
+        "downstream_transport_visibility",
+        "info",
+        { sessionKey: meta.sessionKey || sessionService.peekSessionKey() || undefined },
+        () => ({
+          clientId: meta && meta.clientId ? meta.clientId : null,
+          state: meta && meta.state ? meta.state : null,
+          connectedCount: meta && Number.isFinite(meta.connectedCount) ? meta.connectedCount : null,
+          role: meta && meta.role ? meta.role : null,
+          clientKind: meta && meta.clientKind ? meta.clientKind : null,
+          clientName: meta && meta.clientName ? meta.clientName : null,
+          clientVersion: meta && meta.clientVersion ? meta.clientVersion : null,
+          protocolVersion: meta && meta.protocolVersion ? meta.protocolVersion : null,
+        }),
+      );
+    },
+    httpServer: sharedHttpServer,
+    port: opts.port,
+    host: opts.host,
+    token: opts.token,
+  });
+  if (ownedHttpServer) {
+    ownedHttpServer.on("listening", () => {
+      server.wss.emit("listening");
+    });
+    ownedHttpServer.on("error", (err) => {
+      server.wss.emit("error", err);
+    });
+    listenOwnedRelayHttpServer(ownedHttpServer, opts.host, opts.port);
+  }
+
+  // --- Helpers ---
+
+  function buildStatusObject() {
+    return {
+      openclaw:
+        upstreamRuntime && upstreamRuntime.isConnected()
+          ? "connected"
+          : "disconnected",
+      agent: upstreamRuntime ? upstreamRuntime.getAgentName() : null,
+      session: sessionService.ensureSessionKey(),
+      evenAiEnabled: opts.evenAiEnabled === true,
+    };
+  }
+
+  function cachePages(pages) {
+    const nextRevision = pagesRevision + 1;
+    const next = handler.formatPages(pages, { revision: nextRevision });
+    if (next !== cachedPages) {
+      cachedPages = next;
+      pagesRevision = nextRevision;
+    }
+    return cachedPages;
+  }
+
+  function cacheStatus(statusObj) {
+    const nextRevision = statusRevision + 1;
+    const next = handler.formatStatus(statusObj, { revision: nextRevision });
+    if (next !== cachedStatus) {
+      cachedStatus = next;
+      statusRevision = nextRevision;
+    }
+    return cachedStatus;
+  }
+
+  /**
+   * Recompute pages from conversation state, cache, and broadcast.
+   */
+  function broadcastPages() {
+    const pages = conversationState.getPages();
+    const next = cachePages(pages);
+    if (next !== null) {
+      server.broadcast(next);
+    }
+  }
+
+  /**
+   * Build, cache, and broadcast the current status.
+   */
+  function broadcastStatus() {
+    const next = cacheStatus(buildStatusObject());
+    if (next !== null) {
+      server.broadcast(next);
+    }
+  }
+
+  upstreamRuntime = createUpstreamRuntime({
+    logger,
+    gatewayBridge,
+    conversationState,
+    sessionService,
+    handler,
+    emitDebug,
+    broadcastPages,
+    broadcastStatus,
+    broadcastActivity,
+    resetActivityStatusAdapter,
+    modelsCacheTtlMs: opts.modelsCacheTtlMs,
+    getServer() {
+      return server;
+    },
+    getVoiceRuntime() {
+      return null;
+    },
+  });
+
+  if (opts.evenAiEnabled === true) {
+    evenAiRouter = createEvenAiRouter({
+      sessionService,
+      getRoutingMode() {
+        return evenAiSettingsStore.getSnapshot().routingMode;
+      },
+      dedicatedSessionKey: opts.evenAiDedicatedSessionKey,
+    });
+    evenAiRunWaiter = createEvenAiRunWaiter({
+      gatewayBridge,
+      logger,
+      emitDebug,
+    });
+    evenAiEndpoint = createEvenAiEndpoint({
+      logger,
+      httpServer: sharedHttpServer,
+      enabled: true,
+      externallyRouted: opts.evenAiExternalHttpRouting === true,
+      token: opts.evenAiToken,
+      getSettingsSnapshot() {
+        return evenAiSettingsStore.getSnapshot();
+      },
+      getSystemPrompt() {
+        return evenAiSettingsStore.getSnapshot().systemPrompt;
+      },
+      requestTimeoutMs: opts.evenAiRequestTimeoutMs,
+      maxBodyBytes: opts.evenAiMaxBodyBytes,
+      dedupWindowMs: opts.evenAiDedupWindowMs,
+      gatewayBridge,
+      router: evenAiRouter,
+      runWaiter: evenAiRunWaiter,
+      emitDebug,
+      dispatchOcuClawUserSend(params) {
+        return dispatchOcuClawUserSend(params);
+      },
+      emitListenInterceptRecovery(params) {
+        return emitListenInterceptRecovery(params);
+      },
+      hasConnectedAppClient() {
+        return server ? server.getConnectedAppCount() > 0 : false;
+      },
+      recordFirstSentUserMessage(sessionKey, text) {
+        sessionService.recordFirstSentUserMessage(sessionKey, text);
+      },
+      onSessionRouted(route) {
+        if (!route || route.routingMode !== "background_new") {
+          return;
+        }
+        if (
+          typeof evenAiSettingsStore.recordTrackedThrowawayKey === "function" &&
+          typeof route.sessionKey === "string"
+        ) {
+          evenAiSettingsStore.recordTrackedThrowawayKey(route.sessionKey);
+        }
+      },
+      async shouldSeedThinkingForRoute(params) {
+        const route = params && params.route ? params.route : params;
+        const routingMode =
+          route && typeof route.routingMode === "string"
+            ? route.routingMode.trim().toLowerCase()
+            : "active";
+        const thinkingLevel =
+          params && typeof params.thinkingLevel === "string"
+            ? params.thinkingLevel.trim().toLowerCase()
+            : "";
+        const sessionKey =
+          route && typeof route.sessionKey === "string" ? route.sessionKey.trim() : "";
+        if (!thinkingLevel || !sessionKey || routingMode === "active") {
+          return false;
+        }
+        if (routingMode === "background_new") {
+          return true;
+        }
+        if (routingMode !== "background") {
+          return false;
+        }
+        try {
+          const existingSessions = await sessionService.getSessionsByExactKeys([sessionKey]);
+          return existingSessions.length === 0;
+        } catch {
+          return false;
+        }
+      },
+      onSessionActivated(route) {
+        if (!route || !route.sessionChanged) {
+          return;
+        }
+        server.broadcast(handler.formatSessionSwitched(route.sessionKey));
+        if (cachedPages !== null) {
+          server.broadcast(cachedPages);
+        }
+      },
+      isUpstreamConnected() {
+        return upstreamRuntime ? upstreamRuntime.isConnected() : false;
+      },
+    });
+  }
+
+  // --- Public API ---
+
+  return {
+    /**
+     * Start the upstream OpenClaw connection.
+     * The downstream server is already listening from construction.
+     */
+    start() {
+      return Promise.resolve(gatewayBridge.start()).then(() => {
+        prefetchSonioxModels("relay_start").catch((err) => {
+          logger.warn(`[relay] Soniox models prefetch failed: ${err.message}`);
+        });
+        if (upstreamRuntime && typeof upstreamRuntime.start === "function") {
+          return upstreamRuntime.start();
+        }
+      });
+    },
+
+    /**
+     * Stop the upstream connection and shut down the downstream server.
+     *
+     * @returns {Promise<void>}
+     */
+    stop() {
+      clearSimulateStreamTimers();
+      if (evenAiEndpoint) {
+        evenAiEndpoint.close();
+      }
+      if (evenAiRunWaiter) {
+        evenAiRunWaiter.close();
+      }
+      if (upstreamRuntime) {
+        upstreamRuntime.stop();
+      }
+      gatewayBridge.stop();
+      return Promise.resolve(server.close()).then(() =>
+        closeOwnedRelayHttpServer(ownedHttpServer),
+      );
+    },
+
+    handleEvenAiHttpRequest(req, res) {
+      if (!evenAiEndpoint || typeof evenAiEndpoint.handleRequest !== "function") {
+        return Promise.resolve(false);
+      }
+      return Promise.resolve(evenAiEndpoint.handleRequest(req, res));
+    },
+
+    /** The downstream server instance. */
+    get server() {
+      return server;
+    },
+
+    get httpServer() {
+      return sharedHttpServer;
+    },
+
+    getEvenAiSettingsSnapshot() {
+      return evenAiSettingsStore.getSnapshot();
+    },
+  };
+}
+
+const createRelayCore = createRelay;
+
+export { createRelayCore, createRelay };