ocuclaw 1.3.2 → 1.3.4

package/dist/runtime/relay-core.js

@@ -1,9 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as crypto from "node:crypto";
+import * as os from "node:os";
 import { EventEmitter } from "node:events";
 import { createPluginVersionService } from "./plugin-version-service.js";
 import * as conversationStateModule from "../domain/conversation-state.js";
 import { createDebugStore } from "../domain/debug-store.js";
+import { startUploadCaptureArming, UPLOAD_CAPTURE_PRESET } from "../domain/debug-upload-preset.js";
 import { summarizeGlassesUiContent } from "../domain/glasses-ui-content-summary.js";
 import { composeReadabilitySystemPrompt } from "../domain/readability-system-prompt.js";
 import { composeNeuralEmojiReactorSystemPrompt } from "../domain/neural-emoji-reactor-system-prompt.js";
@@ -15,12 +18,23 @@ import { createActivityStatusAdapter } from "../domain/activity-status-adapter.j
 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 {
+  createEvenAiSettingsStore,
+  normalizeEvenAiDefaultAgent,
+} from "../even-ai/even-ai-settings-store.js";
 import { createPluginOpenclawClient } from "../gateway/openclaw-client.js";
 import { createPluginRpcGatewayBridge } from "../gateway/gateway-bridge.js";
+import { createAgentTurnTracker } from "../tools/glasses-ui-wake.js";
 import { createDownstreamHandler } from "./downstream-handler.js";
-import { createOcuClawSettingsStore } from "./ocuclaw-settings-store.js";
+import { handleDebugBundleRequest, handleDebugBundleSave, handleDebugBundleFetch } from "./debug-bundle-handler.js";
+import { createBundleCache } from "../domain/debug-bundle-cache.js";
+import { saveBundleToDisk } from "../domain/debug-bundle-save.js";
+import {
+  createOcuClawSettingsStore,
+  normalizeOcuClawDefaultAgent,
+} from "./ocuclaw-settings-store.js";
 import { createRelayHealthMonitor } from "./relay-health-monitor.js";
+import { createGlassesBackpressureLatch } from "./glasses-backpressure-latch.js";
 import { createRelayOperationRegistry } from "./relay-operation-registry.js";
 import { createRelayWorkerSupervisor } from "./relay-worker-supervisor.js";
 import {
@@ -29,13 +43,18 @@ import {
 } from "./session-service.js";
 import { createUpstreamRuntime } from "./upstream-runtime.js";
 
+const GLASSES_UI_MARKERS = new Set(["listening", "parked", "inflight"]);
+export function sanitizeGlassesMarker(v) { return GLASSES_UI_MARKERS.has(v) ? v : undefined; }
+
 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;
-// Maximum time (ms) to wait for a Soniox temp-key mint before aborting the
-// fetch.  8 s is a conservative cold-path ceiling; tests inject a tiny value
-// via opts.sonioxTemporaryKeyMintTimeoutMs to make assertions fast.
+
 const DEFAULT_SONIOX_TEMP_KEY_MINT_TIMEOUT_MS = 8000;
+const CARTESIA_ACCESS_TOKEN_URL = "https://api.cartesia.ai/access-token";
+const CARTESIA_VERSION = "2026-03-01";
+const DEFAULT_CARTESIA_ACCESS_TOKEN_EXPIRES_IN_SECONDS = 3600;
+const DEFAULT_CARTESIA_ACCESS_TOKEN_MINT_TIMEOUT_MS = 8000;
 const EVEN_AI_NAMESPACE_PREFIX = "ocuclaw:even-ai";
 const EVEN_AI_NAMESPACE_PREFIX_WITH_DELIMITER = "ocuclaw:even-ai:";
 const LISTEN_INTERCEPT_RECOVERY_ERROR = "Voice interrupted; retry";
@@ -174,7 +193,7 @@ function normalizeSonioxTemporaryKeyErrorCode(err) {
       : "";
   const lowered = message.toLowerCase();
   if (!message) return "soniox_temp_key_request_failed";
-  // AbortError from the per-fetch timeout AbortController.
+
   if (err && err.name === "AbortError") {
     return "soniox_temp_key_mint_timeout";
   }
@@ -256,9 +275,7 @@ function createBufferedHttpResponse(maxResponseBytes) {
   const limit = Number.isFinite(maxResponseBytes) && maxResponseBytes > 0
     ? Math.floor(maxResponseBytes)
     : 262_144;
-  // EventEmitter shape: handlers like the Even-AI endpoint subscribe to
-  // res.once('close', ...) for client-disconnect detection. Worker-mode
-  // relays actual client closes through an http.cancel worker message.
+
   const res = new EventEmitter();
   res.statusCode = 200;
   res.writableEnded = false;
@@ -296,29 +313,18 @@ function createBufferedHttpResponse(maxResponseBytes) {
   return res;
 }
 
-// --- 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 allowDebugUpload = opts.allowDebugUpload === true;
+
+  const debugUploadMaxZipBytes =
+    Number.isFinite(opts.debugUploadMaxZipBytes) && opts.debugUploadMaxZipBytes > 0
+      ? Math.floor(opts.debugUploadMaxZipBytes)
+      : 4_000_000;
+
+  const debugBundleIdSalt = crypto.randomBytes(16).toString("hex");
   const openclawClient =
     opts.openclawClient ||
     (opts.gatewayBridge
@@ -342,30 +348,23 @@ function createRelay(opts) {
   const activityStatusAdapter = createActivityStatusAdapter(
     opts.activityStatusAdapter,
   );
-  const sharedHttpServer = opts.httpServer || null;
 
-  // --- Cached state ---
+  const agentTurnTracker = createAgentTurnTracker();
+  const sharedHttpServer = opts.httpServer || null;
 
-  /** @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;
-  /** @type {{sessionKey: string, modelProvider: string|null, model: string|null, thinkingLevel: string, reasoningLevel: string, verboseLevel: string}|null} */
+
   let currentSessionModelConfigSnapshot = null;
 
-  /** Relay-local deterministic simulate-stream run sequence counter. */
   let simulateStreamRunSeq = 0;
-  /** Active timers for relay-local deterministic simulate-stream runs. */
-  // timer -> sessionKey, so new-chat//reset/new-session can cancel ONLY the
-  // affected session's pending injections (re-land of a8a29032, session-scoped).
-  const simulateStreamTimers = new Map();
 
-  // --- Structured debug state ---
+  const simulateStreamTimers = new Map();
 
   const debugCategories = Array.isArray(opts.debugCategories)
     ? opts.debugCategories
@@ -374,21 +373,10 @@ function createRelay(opts) {
           .filter(([, enabled]) => enabled)
           .map(([category]) => category)
       : opts.debugCategories;
-  // Single relay-side clock: the debug store, the emitDebug ts stamp, and the
-  // liveui log tee all read from this one source so store records and `[liveui]`
-  // log lines share an identical ts (downstream reconcilers dedupe on it).
+
   const debugNow =
     typeof opts.debugNow === "function" ? opts.debugNow : () => Date.now();
 
-  // --- Durable debug-store arm (survives relay/gateway restarts) ---
-  // The capture arm (enabled categories + TTLs) lives only in the in-memory
-  // debug-store, which a restart rebuilds empty. We persist it to debug-arm.json
-  // (via persistDebugArm) and rehydrate it here at construction — read-once,
-  // mirroring liveUiTraceFlagPath below — so a restart no longer silently drops
-  // capture. This path covers process RESTART only: a pure WebUI *reload* does NOT
-  // restart the relay and already preserves + re-advertises the arm via
-  // relay-worker-transport.ts:327-328 (cache.debugConfig re-broadcast to app
-  // clients) — do not add reconnect machinery here.
   const debugArmStatePath =
     typeof opts.stateDir === "string" && opts.stateDir
       ? path.join(opts.stateDir, "debug-arm.json")
@@ -407,7 +395,6 @@ function createRelay(opts) {
   const debugStore = createDebugStore({
     categories: debugCategories,
     capacity: opts.debugCapacity,
-    payloadMaxBytes: opts.debugPayloadMaxBytes,
     defaultTtlMs: opts.debugDefaultTtlMs,
     maxTtlMs: opts.debugMaxTtlMs,
     dumpDefaultLimit: opts.debugDumpDefaultLimit,
@@ -417,10 +404,14 @@ function createRelay(opts) {
     initialEnabled: initialDebugArm,
   });
 
-  // --- Live-interface trace-log flag (durable across restarts) ---
-  // Gates the glasses.lifecycle → gateway-log tee. Read once at construction;
-  // toggled live by applyTraceLogSet, which also rewrites this file so the
-  // value survives a relay/gateway restart (the store's enable-state does not).
+  const bundleCache = createBundleCache({ maxEntries: 4, ttlMs: 5 * 60_000, now: () => Date.now() });
+  let bundleCacheSweepTimer = null;
+
+  function resolveSaveDir() {
+    const c = opts.debugBundleSaveDir;
+    return (typeof c === "string" && c.trim()) ? c : path.join(os.homedir(), ".openclaw", "ocuclaw-debug-bundles");
+  }
+
   const liveUiTraceFlagPath =
     typeof opts.stateDir === "string" && opts.stateDir
       ? path.join(opts.stateDir, "liveui-trace.json")
@@ -435,13 +426,11 @@ function createRelay(opts) {
     }
   }
 
-  // --- 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, "");
@@ -450,13 +439,6 @@ function createRelay(opts) {
   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}`);
@@ -466,7 +448,7 @@ function createRelay(opts) {
     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) {
@@ -478,16 +460,6 @@ function createRelay(opts) {
     }
   }
 
-  /**
-   * 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, options) {
     const force = !!(options && options.force === true);
     if (!force && !debugStore.isEnabled(cat) && !(liveUiTraceLogEnabled && (cat === "glasses.lifecycle" || cat === "openclaw.message"))) {
@@ -512,8 +484,6 @@ function createRelay(opts) {
 
     debugStore.emit(payload, { force });
 
-    // Durable openclaw-side trace tee (gated by the persistent flag, NOT the
-    // store category enable). Must never throw into the emit path.
     if (liveUiTraceLogEnabled && (cat === "glasses.lifecycle" || cat === "openclaw.message")) {
       try {
         const surfaceId =
@@ -541,7 +511,7 @@ function createRelay(opts) {
             }),
         );
       } catch {
-        // observability must never break the emit path
+
       }
     }
   }
@@ -609,12 +579,26 @@ function createRelay(opts) {
   )
     ? Math.max(1, Math.floor(opts.sonioxTemporaryKeyMintTimeoutMs))
     : DEFAULT_SONIOX_TEMP_KEY_MINT_TIMEOUT_MS;
-  /** @type {Array<{id: string, name: string, supportsMaxEndpointDelay: boolean}>|null} */
+  const configuredCartesiaApiKey =
+    opts.cartesiaApiKey !== undefined
+      ? opts.cartesiaApiKey
+      : (opts.config && opts.config.cartesiaApiKey) || "";
+  const cartesiaAccessTokenExpiresInSeconds = Number.isFinite(
+    opts.cartesiaAccessTokenExpiresInSeconds,
+  )
+    ? Math.max(30, Math.min(3600, Math.floor(opts.cartesiaAccessTokenExpiresInSeconds)))
+    : DEFAULT_CARTESIA_ACCESS_TOKEN_EXPIRES_IN_SECONDS;
+  const cartesiaAccessTokenMintTimeoutMs = Number.isFinite(
+    opts.cartesiaAccessTokenMintTimeoutMs,
+  )
+    ? Math.max(1, Math.floor(opts.cartesiaAccessTokenMintTimeoutMs))
+    : DEFAULT_CARTESIA_ACCESS_TOKEN_MINT_TIMEOUT_MS;
+
   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() {
@@ -926,6 +910,138 @@ function createRelay(opts) {
     }
   }
 
+  function normalizeCartesiaAccessTokenResult(result, voiceSessionId, nowMs) {
+    const accessToken =
+      pickTrimmedString(result && (result.accessToken || result.token)) || "";
+    if (!accessToken) {
+      throw new Error("Cartesia access-token response missing token");
+    }
+    const expiresInSeconds = Number.isFinite(result && result.expiresInSeconds)
+      ? result.expiresInSeconds
+      : cartesiaAccessTokenExpiresInSeconds;
+    const expiresAtMs = Number.isFinite(result && result.expiresAtMs)
+      ? Math.floor(result.expiresAtMs)
+      : Math.floor(nowMs + expiresInSeconds * 1000);
+    return { voiceSessionId, accessToken, expiresAtMs };
+  }
+
+  async function mintCartesiaAccessToken(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] cartesia access token issued: clientId=${clientId} voiceSessionId=${voiceSessionId} source=${source} expiresAtMs=${normalized.expiresAtMs}`,
+      );
+      emitDebug(
+        "voice.timeline",
+        "cartesia_access_token_issued",
+        "info",
+        { sessionKey: resolvedSessionKey },
+        () => ({ clientId, voiceSessionId, expiresAtMs: normalized.expiresAtMs, source }),
+      );
+      return normalized;
+    };
+
+    try {
+      if (typeof opts.createCartesiaAccessToken === "function") {
+        const overrideResult = await Promise.resolve(
+          opts.createCartesiaAccessToken({
+            voiceSessionId,
+            sessionKey,
+            expiresInSeconds: cartesiaAccessTokenExpiresInSeconds,
+          }),
+        );
+        return emitIssued(
+          normalizeCartesiaAccessTokenResult(overrideResult || {}, voiceSessionId, nowMs),
+          "override",
+        );
+      }
+
+      if (!configuredCartesiaApiKey) {
+        throw new Error("Cartesia API key is not configured");
+      }
+      const fetchImpl = resolveFetchImpl();
+      if (!fetchImpl) {
+        throw new Error("fetch is not available for Cartesia access-token minting");
+      }
+
+      const mintAbortController = new AbortController();
+      const mintTimeoutTimer = setTimeout(
+        () => mintAbortController.abort(),
+        cartesiaAccessTokenMintTimeoutMs,
+      );
+      let response;
+      try {
+        response = await fetchImpl(CARTESIA_ACCESS_TOKEN_URL, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${configuredCartesiaApiKey}`,
+            "Cartesia-Version": CARTESIA_VERSION,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            grants: { stt: true },
+            expires_in: cartesiaAccessTokenExpiresInSeconds,
+          }),
+          signal: mintAbortController.signal,
+        });
+      } finally {
+        clearTimeout(mintTimeoutTimer);
+      }
+
+      const rawText =
+        response && typeof response.text === "function" ? await response.text() : "";
+      let payload = {};
+      if (rawText) {
+        try {
+          payload = JSON.parse(rawText);
+        } catch (err) {
+          throw new Error(
+            `Cartesia access-token response was not valid JSON (${response.status})`,
+          );
+        }
+      }
+      if (!response.ok) {
+        const errorDetail =
+          pickTrimmedString(
+            payload && payload.message,
+            payload && payload.error,
+            rawText,
+          ) || `HTTP ${response.status}`;
+        throw new Error(
+          `Cartesia access-token request failed (${response.status}): ${tailForLog(errorDetail)}`,
+        );
+      }
+
+      return emitIssued(
+        normalizeCartesiaAccessTokenResult(
+          { token: payload && payload.token },
+          voiceSessionId,
+          nowMs,
+        ),
+        "cartesia_api",
+      );
+    } catch (err) {
+      const message = err && err.message ? err.message : "Cartesia access-token request failed";
+      logger.warn(
+        `[relay] cartesia access token failed: clientId=${clientId} voiceSessionId=${voiceSessionId} message=${tailForLog(message)}`,
+      );
+      emitDebug(
+        "voice.timeline",
+        "cartesia_access_token_failed",
+        "warn",
+        { sessionKey: resolvedSessionKey },
+        () => ({ clientId, voiceSessionId, message: tailForLog(message) }),
+      );
+      throw err;
+    }
+  }
+
   let upstreamRuntime = null;
   const evenAiSettingsStore = createEvenAiSettingsStore({
     logger,
@@ -948,16 +1064,11 @@ function createRelay(opts) {
     stateDir: opts.stateDir,
     emitDebug,
   });
-  // Hourly TTL sweep for stale stable-prompt snapshots; started in start(),
-  // cleared in stop(). Declared here so both can see it.
+
   let stablePromptSweepTimer = null;
 
-  // Channel 1: the per-session-immutable extraSystemPrompt. Computed once from
-  // the feature set AT SESSION START and then served byte-identical for the
-  // session's lifetime (see stable-prompt-snapshot). Mid-session toggles are
-  // bridged by the Channel-2 hook composer, NOT here. The glasses-UI pointer is
-  // always present (its disconnected gate moved to Channel 2); the emoji/pace
-  // blocks are included only when active at session start.
+  let uploadCaptureArmingDisposer = null;
+
   function computeStableChannelOne(startSignals) {
     const baseReadability = composeReadabilitySystemPrompt(
       ocuClawSettingsStore.getSnapshot().systemPrompt,
@@ -976,8 +1087,7 @@ function createRelay(opts) {
 
   function stableSendOptions(resolvedSessionKey, sessionId, perTurnSignals) {
     const signals = perTurnSignals || {};
-    // "enabled at start" = the client's reported state on the FIRST send of the
-    // session. The 3-state client signal maps to a boolean: only "active" counts.
+
     const startEmoji = signals.neuralEmojiReactorState === "active";
     const startPace = signals.neuralPaceModulatorState === "active";
     const extraSystemPrompt = stablePromptSnapshots.getOrCreate(
@@ -985,10 +1095,7 @@ function createRelay(opts) {
       sessionId,
       () => computeStableChannelOne({ emoji: startEmoji, pace: startPace }),
     );
-    // Churn guard: if recomputing TODAY would differ from the served snapshot,
-    // something is mutating Channel 1 mid-session (e.g. a toggle flipped the
-    // start-state signals) — the case that used to reset the CLI session.
-    // Surface it loudly; the served prompt stays the frozen snapshot.
+
     if (
       stablePromptSnapshots.wouldChurn(
         resolvedSessionKey,
@@ -1004,7 +1111,13 @@ function createRelay(opts) {
         () => ({ sessionId: sessionId || null }),
       );
     }
-    return { extraSystemPrompt };
+    const options = { extraSystemPrompt };
+
+    const agentId = sessionService.getSessionAgentId(resolvedSessionKey);
+    if (typeof agentId === "string" && agentId.trim()) {
+      options.agentId = agentId.trim();
+    }
+    return options;
   }
 
   function buildOcuClawSendDiagnostic(params = {}) {
@@ -1066,6 +1179,36 @@ function createRelay(opts) {
     return userContent;
   }
 
+  function buildGatewayAttachment(attachment) {
+    if (
+      !attachment ||
+      typeof attachment !== "object" ||
+      typeof attachment.base64Data !== "string" ||
+      !attachment.base64Data
+    ) {
+      return null;
+    }
+    const normalizedAttachment = {
+      type: attachment.kind || "image",
+      mimeType: attachment.mimeType || "image/jpeg",
+      fileName: attachment.name || "image.jpg",
+      content: attachment.base64Data,
+    };
+    if (typeof attachment.source === "string" && attachment.source) {
+      normalizedAttachment.source = attachment.source;
+    }
+    if (Number.isFinite(attachment.sizeBytes) && attachment.sizeBytes > 0) {
+      normalizedAttachment.sizeBytes = Math.floor(attachment.sizeBytes);
+    }
+    if (Number.isFinite(attachment.widthPx) && attachment.widthPx > 0) {
+      normalizedAttachment.widthPx = Math.floor(attachment.widthPx);
+    }
+    if (Number.isFinite(attachment.heightPx) && attachment.heightPx > 0) {
+      normalizedAttachment.heightPx = Math.floor(attachment.heightPx);
+    }
+    return normalizedAttachment;
+  }
+
   function buildOcuClawInitialSessionConfigPatch(settings) {
     const patch = {};
     if (settings && typeof settings.defaultModel === "string" && settings.defaultModel.trim()) {
@@ -1084,6 +1227,30 @@ function createRelay(opts) {
     return Object.keys(patch).length > 0 ? patch : null;
   }
 
+  function seedSessionAgentDefault(sessionKey, defaultAgent) {
+    if (
+      !sessionKey ||
+      !sessionService ||
+      typeof sessionService.setSessionAgentId !== "function" ||
+      typeof sessionService.getSessionAgentId !== "function"
+    ) {
+      return;
+    }
+    const normalized =
+      typeof defaultAgent === "string" ? defaultAgent.trim() : "";
+    if (!normalized) {
+      return;
+    }
+    if (
+      typeof sessionService.hasExplicitSessionAgent === "function" &&
+      sessionService.hasExplicitSessionAgent(sessionKey)
+    ) {
+
+      return;
+    }
+    sessionService.setSessionAgentId(sessionKey, normalized);
+  }
+
   async function maybeSeedOcuClawSessionConfig(sessionKey) {
     if (
       !sessionKey ||
@@ -1095,6 +1262,7 @@ function createRelay(opts) {
     }
 
     const settings = ocuClawSettingsStore.getSnapshot();
+    seedSessionAgentDefault(sessionKey, settings.defaultAgent);
     const patch = buildOcuClawInitialSessionConfigPatch(settings);
     if (!patch) {
       sessionService.clearPendingInitialConfig(sessionKey);
@@ -1122,6 +1290,7 @@ function createRelay(opts) {
     }
 
     const settings = ocuClawSettingsStore.getSnapshot();
+    seedSessionAgentDefault(sessionKey, settings.defaultAgent);
     const patch = buildOcuClawInitialSessionConfigPatch(settings);
     if (!patch) {
       return null;
@@ -1154,6 +1323,17 @@ function createRelay(opts) {
     getAgentName() {
       return upstreamRuntime ? upstreamRuntime.getAgentName() : null;
     },
+    getAgentDisplayName(agentId) {
+      return upstreamRuntime &&
+        typeof upstreamRuntime.getAgentDisplayName === "function"
+        ? upstreamRuntime.getAgentDisplayName(agentId)
+        : null;
+    },
+    getDefaultAgentId() {
+      return normalizeOcuClawDefaultAgent(
+        ocuClawSettingsStore.getSnapshot().defaultAgent,
+      );
+    },
     isPinnedFirstUserMessageKey(sessionKey) {
       const normalizedSessionKey = normalizeEvenAiSessionKeyForLookup(sessionKey);
       if (!normalizedSessionKey) {
@@ -1247,13 +1427,6 @@ function createRelay(opts) {
     }
   }
 
-  // TTL fallback for set_session_title activity label. The tool itself
-  // completes in <50ms but its label can linger if no follow-up activity
-  // arrives (e.g. agent streams a response directly after, with no
-  // intervening activity event). After 1s, synthesize a thinking-status
-  // activity with no tool/label so the renderer falls back to the bare
-  // animated spinner. Any real activity arriving in the meantime cancels
-  // the timer.
   const SESSION_TITLE_STATUS_FALLBACK_MS = 1500;
   let sessionTitleStatusFallbackTimer = null;
 
@@ -1262,6 +1435,10 @@ function createRelay(opts) {
     const runId = activity && activity.runId ? activity.runId : null;
     const origin = activity && activity.origin ? activity.origin : null;
     const phase = activity && activity.phase ? activity.phase : null;
+    agentTurnTracker.onActivity(
+      (activity && activity.sessionKey) || sessionService.ensureSessionKey(),
+      phase,
+    );
 
     emitDebug(
       "app.timeline",
@@ -1324,6 +1501,20 @@ function createRelay(opts) {
     return snapshot;
   }
 
+  function broadcastAgentsCatalog(snapshot) {
+    if (!server || !handler || typeof handler.formatAgentsCatalog !== "function") {
+      return snapshot;
+    }
+
+    const agents =
+      snapshot && Array.isArray(snapshot.agents) ? snapshot.agents : [];
+    if (agents.length === 0 && !(snapshot && snapshot.unsupported)) {
+      return snapshot;
+    }
+    server.broadcast(handler.formatAgentsCatalog(snapshot || {}));
+    return snapshot;
+  }
+
   const appClientDisconnectHandlers = new Set();
   function onAppClientDisconnect(handler) {
     if (typeof handler !== "function") return () => {};
@@ -1348,6 +1539,7 @@ function createRelay(opts) {
       surfaceId: params && typeof params.surfaceId === "string" ? params.surfaceId : "",
       depth: Number.isFinite(params && params.depth) ? Math.floor(params.depth) : 1,
       spec: params && params.spec ? params.spec : null,
+      marker: sanitizeGlassesMarker(params && params.marker),
     };
     server.broadcast(JSON.stringify(payload));
     emitDebug(
@@ -1367,9 +1559,7 @@ function createRelay(opts) {
     if (typeof patch.title === "string") cleanPatch.title = patch.title;
     if (typeof patch.body === "string") cleanPatch.body = patch.body;
     if (Array.isArray(patch.items)) {
-      // Items may be plain-string labels (list_surface / label-only) OR
-      // {label, body} objects (list_with_details detail-body ticks). Keep both
-      // shapes; drop anything malformed (no string, no string label).
+
       cleanPatch.items = patch.items
         .map((i) => {
           if (typeof i === "string") return i;
@@ -1382,6 +1572,7 @@ function createRelay(opts) {
         })
         .filter((i) => i !== null);
     }
+    const m = sanitizeGlassesMarker(patch.marker); if (m) cleanPatch.marker = m;
     const payload = {
       type: "glasses_ui_surface_update",
       sessionKey: params && typeof params.sessionKey === "string" ? params.sessionKey : null,
@@ -1542,8 +1733,9 @@ function createRelay(opts) {
     );
 
     return maybeSeedOcuClawSessionConfig(resolvedSessionKey).then(() => {
-      // Dispatch upstream first so local transcript work cannot delay first
-      // model tokens on large histories.
+
+      agentTurnTracker.markBusy(resolvedSessionKey);
+
       const upstreamPromise = gatewayBridge.sendMessage(
         text,
         resolvedSessionKey,
@@ -1551,11 +1743,7 @@ function createRelay(opts) {
         {
           ...stableSendOptions(
             resolvedSessionKey,
-            // No synchronous OpenClaw sessionId is available at send time
-            // (resolveSessionCanonicalKey is async). Use the sessionKey as the
-            // snapshot's id; the sessionId-mismatch guard is therefore a no-op,
-            // and new-session safety rests on logical-session-end eviction
-            // (onNewSession / onNewChat / onDeleteSessions evict the snapshot).
+
             resolvedSessionKey,
             clientDisplaySignals,
           ),
@@ -1657,6 +1845,107 @@ function createRelay(opts) {
     });
   }
 
+  function dispatchOcuClawSessionAbort(params = {}) {
+    const requestId = params.requestId;
+    const sessionKey =
+      typeof params.sessionKey === "string" && params.sessionKey.trim()
+        ? params.sessionKey.trim()
+        : sessionService.ensureSessionKey();
+    emitDebug(
+      "relay.protocol",
+      "session_abort_requested",
+      "info",
+      { sessionKey },
+      () => ({ requestId }),
+    );
+    return gatewayBridge.request("sessions.abort", { key: sessionKey }).then(
+      (result) => ({
+        status: "accepted",
+        ...(result && typeof result === "object" ? result : {}),
+      }),
+    );
+  }
+
+  function dispatchOcuClawSessionSteer(params = {}) {
+    const requestId = params.requestId;
+    const steerStartedAt = Date.now();
+    const sessionKey =
+      typeof params.sessionKey === "string" && params.sessionKey.trim()
+        ? params.sessionKey.trim()
+        : sessionService.ensureSessionKey();
+    const message = typeof params.message === "string" ? params.message : "";
+    const attachment = params.attachment || null;
+    const gatewayAttachment = buildGatewayAttachment(attachment);
+    const request = {
+      key: sessionKey,
+      message,
+      idempotencyKey: requestId,
+    };
+    if (gatewayAttachment) {
+      request.attachments = [gatewayAttachment];
+    }
+
+    sessionService.recordFirstSentUserMessage(sessionKey, message);
+    sessionService.invalidateSessionsCache();
+    agentTurnTracker.markBusy(sessionKey);
+    emitDebug(
+      "relay.protocol",
+      "session_steer_requested",
+      "info",
+      { sessionKey },
+      () => ({
+        requestId,
+        messageChars: message.length,
+        hasAttachment: !!attachment,
+      }),
+    );
+
+    const diagnostic = {
+      messageId: requestId,
+      sessionKey,
+      source: "phone_ui_replace",
+      textChars: message.length,
+      hasAttachment: !!attachment,
+      attachmentBytes:
+        attachment && Number.isFinite(attachment.sizeBytes)
+          ? Math.floor(attachment.sizeBytes)
+          : null,
+    };
+
+    return maybeSeedOcuClawSessionConfig(sessionKey)
+      .then(() => gatewayBridge.request("sessions.steer", request, {
+        expectFinal: false,
+        diagnostic,
+      }))
+      .then((result) => {
+        const ackAt = Date.now();
+        const runId = result && result.runId ? result.runId : null;
+        if (runId && upstreamRuntime) {
+          upstreamRuntime.trackAcceptedRun({
+            runId,
+            sessionKey,
+            messageId: requestId,
+            sendStartedAt: steerStartedAt,
+            ackAt,
+          });
+        }
+        const userContent = buildLocalUserMessageContent(message, attachment);
+        conversationState.addMessage("user", userContent);
+        emitDebug(
+          "openclaw.message",
+          "user_message",
+          "info",
+          { sessionKey },
+          () => ({ text: message }),
+        );
+        broadcastPages();
+        return {
+          ...(result && typeof result === "object" ? result : {}),
+          status: "accepted",
+        };
+      });
+  }
+
   function emitListenInterceptRecovery(params = {}) {
     const connectedAppClients = server ? server.getConnectedAppCount() : 0;
     if (!server || !handler) {
@@ -1687,9 +1976,6 @@ function createRelay(opts) {
     server.broadcast(handler.formatEvenAiListenIntercepted(sessionKey));
   }
 
-  // --- Downstream handler ---
-
-  /** @type {ReturnType<typeof createRelayWorkerSupervisor>|null} */
   let server = null;
   let evenAiEndpoint = null;
   let evenAiRouter = null;
@@ -1713,12 +1999,6 @@ function createRelay(opts) {
     return { ok: true, enabled, persisted, persistedPath: liveUiTraceFlagPath };
   }
 
-  // Persist the current debug-store arm to debug-arm.json. Mirrors the
-  // applyTraceLogSet writeFileSync above (plain, non-atomic): a partial/corrupt
-  // write degrades to an empty arm on next boot — acceptable, the nothing-armed
-  // warning catches it. getSnapshot().enabled is already pruned of expired
-  // categories, so the persisted JSON never holds an expired entry. Never throws
-  // into the caller.
   function persistDebugArm() {
     if (!debugArmStatePath) return false;
     try {
@@ -1736,9 +2016,7 @@ function createRelay(opts) {
     if (!result.ok) {
       throw new Error(result.error || "debug-set failed");
     }
-    // Persist after every successful set — enable AND disable-to-empty — so the
-    // on-disk arm always tracks live state and a deliberately-cleared arm is not
-    // resurrected on the next restart.
+
     persistDebugArm();
     emitDebug(
       "relay.protocol",
@@ -1764,15 +2042,7 @@ function createRelay(opts) {
       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, clientDisplaySignals) {
       return dispatchOcuClawUserSend({
         id,
@@ -1783,6 +2053,17 @@ function createRelay(opts) {
         source: "phone_ui",
       });
     },
+    onAbortSession({ requestId, sessionKey }) {
+      return dispatchOcuClawSessionAbort({ requestId, sessionKey });
+    },
+    onSteerSession({ requestId, sessionKey, message, attachment }) {
+      return dispatchOcuClawSessionSteer({
+        requestId,
+        sessionKey,
+        message,
+        attachment,
+      });
+    },
     onGlassesUiResult(frame) {
       emitDebug(
         "glasses.lifecycle",
@@ -1873,19 +2154,89 @@ function createRelay(opts) {
           }
         });
     },
+
+    onDebugBundleRequest(clientId, msg) {
+
+      const reportedClientVersion = (() => {
+        try {
+          const snap =
+            server && typeof server.getReadinessSnapshot === "function"
+              ? server.getReadinessSnapshot()
+              : null;
+          const entry =
+            snap && Array.isArray(snap.clients)
+              ? snap.clients.find((c) => c.clientId === clientId)
+              : null;
+          const v = entry && typeof entry.clientVersion === "string" ? entry.clientVersion.trim() : "";
+          return v.length ? v : null;
+        } catch {
+          return null;
+        }
+      })();
+      const deps = {
+        gatesOn: () => externalDebugToolsEnabled && allowDebugUpload,
+        dump: (query) => debugStore.dump(query),
+
+        preset:
+          opts.debugUploadCapturePreset &&
+          Array.isArray(opts.debugUploadCapturePreset) &&
+          opts.debugUploadCapturePreset.length
+            ? opts.debugUploadCapturePreset
+            : UPLOAD_CAPTURE_PRESET,
+
+        build: {
+          clientVersion: reportedClientVersion,
+          requiresClientVersion: pluginVersionService.getRequiresClientVersion(),
+          pluginVersion: pluginVersionService.getPluginVersion(),
+          openclawVersion: pluginVersionService.getOpenClawHostVersion(),
+          distHash: pluginVersionService.getDistHash(),
+        },
+        idSalt: debugBundleIdSalt,
+        maxZipBytes: debugUploadMaxZipBytes,
+        chunkBytes: 64000,
+        send: (id, frame) => {
+          if (server) server.unicast(id, JSON.stringify(frame));
+        },
+
+        emit: (event, data) =>
+          emitDebug("relay.operation", event, "debug", {}, () => data),
+        newBundleId: () => crypto.randomUUID(),
+        cachePut: (id, e) => bundleCache.put(id, e),
+        now: () => Date.now(),
+      };
+      return Promise.resolve(handleDebugBundleRequest(deps, clientId, msg)).catch(
+        (err) => {
+          logger.error(
+            `[relay] debug-bundle-request failed: ${err && err.message ? err.message : err}`,
+          );
+        },
+      );
+    },
+    onDebugBundleSave(clientId, msg) {
+      return Promise.resolve(handleDebugBundleSave({
+        gatesOn: () => externalDebugToolsEnabled && allowDebugUpload,
+        cacheGet: (id) => bundleCache.get(id),
+        saveBundle: (a) => saveBundleToDisk({ ...a, saveDir: resolveSaveDir(), fs, path }),
+        now: () => Date.now(),
+        send: (id, frame) => { if (server) server.unicast(id, JSON.stringify(frame)); },
+        emit: (event, data) => emitDebug("relay.operation", event, "debug", {}, () => data),
+      }, clientId, msg)).catch((err) => {
+        logger.error(`[relay] debug-bundle-save failed: ${err && err.message ? err.message : err}`);
+      });
+    },
+    onDebugBundleFetch(clientId, msg) {
+      return Promise.resolve(handleDebugBundleFetch({
+        gatesOn: () => externalDebugToolsEnabled && allowDebugUpload,
+        cacheGet: (id) => bundleCache.get(id),
+        chunkBytes: 64000,
+        send: (id, frame) => { if (server) server.unicast(id, JSON.stringify(frame)); },
+        emit: (event, data) => emitDebug("relay.operation", event, "debug", {}, () => data),
+      }, clientId, msg)).catch((err) => {
+        logger.error(`[relay] debug-bundle-fetch failed: ${err && err.message ? err.message : err}`);
+      });
+    },
     operationRegistry: relayOperationRegistry,
 
-    /**
-     * 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",
@@ -1897,7 +2248,7 @@ function createRelay(opts) {
           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();
@@ -2015,12 +2366,6 @@ function createRelay(opts) {
       });
     },
 
-    /**
-     * 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",
@@ -2034,15 +2379,10 @@ function createRelay(opts) {
       }
       sessionService.invalidateSessionsCache();
       resetActivityStatusAdapter();
-      // Cancel THIS session's pending simulate-stream timers BEFORE clearing —
-      // a deferred addMessage firing after the clear repopulates the fresh chat
-      // (the 2026-05-15 canary-pollution mechanism).
+
       clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       conversationState.clear();
-      // Logical session end: this key is REUSED for a fresh conversation, so the
-      // Channel-1 snapshot must be dropped or the next send serves a stale prompt,
-      // and ALL other per-session state keyed to it (title + upstream name,
-      // toggles, distiller budget, first-user marker) must be cleared too.
+
       const newChatSessionKey = sessionService.ensureSessionKey();
       stablePromptSnapshots.evict(newChatSessionKey);
       sessionService.clearLogicalSessionState(newChatSessionKey);
@@ -2052,12 +2392,7 @@ function createRelay(opts) {
       const pages = conversationState.getPages();
       cachePages(pages);
       if (upstreamRuntime && upstreamRuntime.isConnected()) {
-        // NOTE: onNewChat targets the hard-coded "main" key (legacy) without
-        // changing currentSessionKey, so it must NOT elicit a welcome turn here:
-        // the turn's events would carry "main" and be dropped by isCurrentSession()
-        // whenever the active session is an ocuclaw:* key. The welcome restore for
-        // the real glasses paths lives in newSession() (New) and onSlashCommand
-        // "/reset" (Reset). Unifying onNewChat onto newSession() is Phase-2 work.
+
         gatewayBridge.sendMessage("/new", "main").catch((err) => {
           logger.error(`[relay] Failed to send /new: ${err.message}`);
         });
@@ -2083,16 +2418,10 @@ function createRelay(opts) {
     },
 
     async onNewSession() {
-      // Cancel pending simulate-stream timers scheduled under the outgoing key
-      // BEFORE the new key is minted — a deferred addMessage firing after the
-      // switch would repopulate the fresh session's shared conversation view.
+
       clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       const result = await sessionService.newSession();
-      // newSession() mints a FRESH key; defensively clear only the NEW key (it
-      // has no snapshot yet). Do NOT touch the previous key: that session stays
-      // resumable via onSwitchSession, and dropping its frozen snapshot would
-      // recompute — and churn — Channel 1 if the user switches back to it. The
-      // previous session's snapshot is released by delete or the TTL sweep.
+
       if (result && typeof result.sessionKey === "string" && result.sessionKey.trim()) {
         stablePromptSnapshots.evict(result.sessionKey);
         sessionService.clearDisplayToggleStates(result.sessionKey);
@@ -2127,6 +2456,20 @@ function createRelay(opts) {
         : Promise.resolve({ skills: [], fetchedAtMs: Date.now(), stale: true });
     },
 
+    onGetAgentsCatalog() {
+      return upstreamRuntime
+        ? upstreamRuntime.getAgentsCatalogSnapshot()
+        : Promise.resolve({
+            agents: [],
+            defaultId: null,
+            mainKey: null,
+            scope: null,
+            fetchedAtMs: Date.now(),
+            stale: true,
+            unsupported: true,
+          });
+    },
+
     onGetProviderUsageSnapshot() {
       return upstreamRuntime
         ? upstreamRuntime.getProviderUsageSnapshot()
@@ -2167,6 +2510,32 @@ function createRelay(opts) {
       return result;
     },
 
+    onSetSessionAgent(patch) {
+      const sessionKey = sessionService.ensureSessionKey();
+      const result = sessionService.setSessionAgentId(
+        sessionKey,
+        (patch && patch.agentId) || "",
+      );
+      if (!result || result.ok !== true) {
+        return {
+          status: "rejected",
+          error: (result && result.reason) || "invalid session agent",
+        };
+      }
+
+      if (typeof sessionService.primeSessionModelConfig === "function") {
+        const config = sessionService.primeSessionModelConfig(sessionKey, {});
+        if (config && isActiveSessionModelConfig(config)) {
+          currentSessionModelConfigSnapshot = config;
+          if (server) {
+            server.broadcast(handler.formatSessionModelConfig(config));
+          }
+        }
+      }
+      broadcastSessions();
+      return { status: "accepted" };
+    },
+
     onGetEvenAiSettings() {
       return evenAiSettingsStore.getSnapshot();
     },
@@ -2216,23 +2585,15 @@ function createRelay(opts) {
         );
         broadcastPages();
       }
-      // A user-typed /new or /reset is a logical session reset on the CURRENT
-      // key (distinct from an automatic CLI session reset, which keeps the same
-      // logical session and must survive). Drop the frozen Channel-1 snapshot so
-      // the next real message recomputes it for the fresh conversation; otherwise
-      // the old conversation's prompt + display start-state bleed into the new one.
+
       if (command === "/new" || command === "/reset") {
         const resetKey = sessionService.ensureSessionKey();
         stablePromptSnapshots.evict(resetKey);
-        // Clear ALL per-session state keyed to the reused key (title + upstream
-        // name, toggles, distiller budget, first-user marker) so nothing from the
-        // old conversation bleeds into the fresh one.
+
         sessionService.clearLogicalSessionState(resetKey);
       }
       if (upstreamRuntime && upstreamRuntime.isConnected()) {
-        // Bare /reset no longer elicits an agent turn on OpenClaw 2026.6.x
-        // (fast-reset). Append the greeting prompt so Reset gets the same
-        // welcome as New. Other slash commands forward verbatim.
+
         const outboundCommand =
           command === "/reset"
             ? `/reset ${NEW_SESSION_GREETING_PROMPT}`
@@ -2245,9 +2606,6 @@ function createRelay(opts) {
       return Promise.resolve();
     },
 
-    /**
-     * @returns {boolean} Whether upstream is connected.
-     */
     isUpstreamConnected() {
       return true;
     },
@@ -2298,6 +2656,10 @@ function createRelay(opts) {
       return mintSonioxTemporaryKey(clientId, request);
     },
 
+    onRequestCartesiaAccessToken(clientId, request) {
+      return mintCartesiaAccessToken(clientId, request);
+    },
+
     onDebugSet(clientId, request) {
       return applyDebugSet(clientId, request);
     },
@@ -2545,14 +2907,7 @@ function createRelay(opts) {
     },
 
     onAutomationState(clientId, request) {
-      // Mirrors onReadinessProbe (above): identify the single connected app
-      // client via the readiness snapshot, then return a dispatch envelope
-      // that downstream-handler.handleAutomationState wraps into
-      // `automationStateRequest`. Without this callback wired, the handler
-      // returns null and the request is silently dropped at the relay —
-      // simctl/debugctl times out with no failure response, no trace event,
-      // no outbox drop. The lack of wiring was found 2026-05-28 while
-      // validating the streaming-thinking-emoji-demotion fix on the sim.
+
       const now = Date.now();
       const requestId =
         (typeof request.requestId === "string" && request.requestId.trim()) ||
@@ -2581,11 +2936,7 @@ function createRelay(opts) {
         targetEntry && typeof targetEntry.clientId === "string"
           ? targetEntry.clientId
           : null;
-      // A connected app client that has never published a readiness snapshot
-      // cannot answer an automation state request; forwarding anyway would
-      // park the request in pendingAutomationStateRequests with no reply.
-      // Same predicate as the downstream readiness gate; this wired callback
-      // bypasses the normal dispatch path.
+
       const readinessPublished =
         !!(
           targetEntry &&
@@ -2672,10 +3023,13 @@ function createRelay(opts) {
     },
   });
 
-  // --- Worker supervisor ---
-
   const pluginVersionService = createPluginVersionService();
 
+  const glassesBackpressureLatch = createGlassesBackpressureLatch({
+    emitDebug: (event, severity, data) =>
+      emitDebug("relay.health", event, severity, null, () => data || {}),
+  });
+
   server = createRelayWorkerSupervisor({
     pluginId: "ocuclaw",
     getPluginVersion: () => pluginVersionService.getPluginVersion(),
@@ -2686,6 +3040,7 @@ function createRelay(opts) {
     host: opts.host,
     port: opts.port,
     token: opts.token,
+    onWorkerBackpressure: (message) => glassesBackpressureLatch.report(message),
     externalDebugToolsEnabled,
     evenAiRequestTimeoutMs: opts.evenAiRequestTimeoutMs,
     evenAiMaxBodyBytes: opts.evenAiMaxBodyBytes,
@@ -2730,8 +3085,6 @@ function createRelay(opts) {
     },
   });
 
-  // --- Helpers ---
-
   function buildStatusObject(options = {}) {
     const includeDownstreamReadiness = options.includeDownstreamReadiness === true;
     const status = {
@@ -2779,9 +3132,6 @@ function createRelay(opts) {
     return cachedStatus;
   }
 
-  /**
-   * Recompute pages from conversation state, cache, and broadcast.
-   */
   function broadcastPages() {
     const pages = conversationState.getPages();
     const next = cachePages(pages);
@@ -2790,12 +3140,6 @@ function createRelay(opts) {
     }
   }
 
-  /**
-   * Fetch the latest sessions snapshot and broadcast it. Used after a session
-   * title changes so connected clients refresh the title in the main webui
-   * status row and Session Settings tab without waiting for a manual
-   * session-list open.
-   */
   function broadcastSessions() {
     sessionService
       .getSessions()
@@ -2813,10 +3157,6 @@ function createRelay(opts) {
       });
   }
 
-  /**
-   * Resolve the current Even AI sessions snapshot for unicast/broadcast.
-   * Mirrors the shape that `formatEvenAiSessions` expects.
-   */
   async function buildEvenAiSessionsSnapshot() {
     const dedicatedKey =
       evenAiRouter && typeof evenAiRouter.getDedicatedSessionKey === "function"
@@ -2881,9 +3221,6 @@ function createRelay(opts) {
       });
   }
 
-  /**
-   * Build, cache, and broadcast the current status.
-   */
   function broadcastStatus() {
     const next = cacheStatus(buildStatusObject());
     if (next !== null) {
@@ -2916,6 +3253,7 @@ function createRelay(opts) {
     broadcastStatus,
     broadcastActivity,
     broadcastProviderUsageSnapshot,
+    broadcastAgentsCatalog,
     operationRegistry: relayOperationRegistry,
     getCurrentSessionModelConfigSnapshot() {
       return currentSessionModelConfigSnapshot;
@@ -2933,10 +3271,6 @@ function createRelay(opts) {
     fetchAgentAvatar: opts.fetchAgentAvatar,
   });
 
-  // Shared routing gate for session-scoped Even AI defaults (thinking seed,
-  // fast-mode patch): never touch active-routed sessions; always seed fresh
-  // background_new sessions; seed persistent background sessions only before
-  // their first turn exists.
   async function shouldSeedSessionScopedDefaultForRoute(route) {
     const routingMode =
       route && typeof route.routingMode === "string"
@@ -3045,6 +3379,29 @@ function createRelay(opts) {
         );
         return !!(result && result.status === "accepted");
       },
+      resolveAgentForRoute(params) {
+        const route = params && params.route ? params.route : params;
+        const routingMode =
+          (route && typeof route.routingMode === "string"
+            ? route.routingMode.trim().toLowerCase()
+            : "") || "active";
+        const sessionKey =
+          route && typeof route.sessionKey === "string"
+            ? route.sessionKey.trim()
+            : "";
+
+        if (routingMode === "active") {
+          return sessionKey ? sessionService.getSessionAgentId(sessionKey) : "";
+        }
+        const evenAiDefault = normalizeEvenAiDefaultAgent(
+          evenAiSettingsStore.getSnapshot().defaultAgent,
+        );
+        if (sessionKey && evenAiDefault) {
+
+          sessionService.setSessionAgentId(sessionKey, evenAiDefault);
+        }
+        return evenAiDefault;
+      },
       onSessionActivated(route) {
         if (!route || !route.sessionChanged) {
           return;
@@ -3105,34 +3462,45 @@ function createRelay(opts) {
     return true;
   }
 
-  // --- Public API ---
-
   relayApi = {
-    /**
-     * Emit a glasses-UI surface-lifecycle event on the permanent
-     * `glasses.lifecycle` debug category (nav reconcile + cron pause/resume/
-     * tick). Recorded only when the category is enabled via debug-set. Wired
-     * through the relay-service facade into the glasses-ui tool handler + cron
-     * engine. See docs/superpowers/findings/2026-05-30-glasses-ui-phase4-hardware.md.
-     */
+
     emitGlassesUiLifecycle(event, severity, data) {
       emitDebug("glasses.lifecycle", event, severity, {}, () => data || {});
     },
-    /**
-     * Start the upstream OpenClaw connection.
-     * The downstream server is already listening from construction.
-    */
+
     start() {
-      // Bounded cleanup of stale stable-prompt snapshots (14-day TTL).
+
+      if (!bundleCacheSweepTimer) {
+        bundleCacheSweepTimer = setInterval(() => bundleCache.sweep(), 60_000);
+        if (typeof bundleCacheSweepTimer.unref === "function") bundleCacheSweepTimer.unref();
+      }
+
       if (!stablePromptSweepTimer) {
         stablePromptSweepTimer = setInterval(
           () => stablePromptSnapshots.sweep(),
-          60 * 60 * 1000, // hourly
+          60 * 60 * 1000,
         );
         if (typeof stablePromptSweepTimer.unref === "function") {
           stablePromptSweepTimer.unref();
         }
       }
+
+      if (!uploadCaptureArmingDisposer) {
+        uploadCaptureArmingDisposer = startUploadCaptureArming({
+          gatesOn: () => externalDebugToolsEnabled && allowDebugUpload,
+          armCategories: (cats, ttlMs) =>
+            applyDebugSet("upload-capture-arming", { enable: cats, ttlMs }),
+          maxTtlMs: debugStore.getConfig().maxTtlMs,
+
+          preset: opts.debugUploadCapturePreset,
+          onArmError: (err) =>
+            logger.warn(
+              `[relay] upload-capture arming failed (preset override?): ${err && err.message}`,
+            ),
+          setInterval,
+          clearInterval,
+        });
+      }
       const startGateway = () => Promise.resolve(gatewayBridge.start()).then(() => {
         prefetchSonioxModels("relay_start").catch((err) => {
           logger.warn(`[relay] Soniox models prefetch failed: ${err.message}`);
@@ -3147,17 +3515,20 @@ function createRelay(opts) {
       return startGateway();
     },
 
-    /**
-     * Stop the upstream connection and shut down the downstream server.
-     *
-     * @returns {Promise<void>}
-     */
     stop() {
       clearSimulateStreamTimers();
+      if (bundleCacheSweepTimer) {
+        clearInterval(bundleCacheSweepTimer);
+        bundleCacheSweepTimer = null;
+      }
       if (stablePromptSweepTimer) {
         clearInterval(stablePromptSweepTimer);
         stablePromptSweepTimer = null;
       }
+      if (uploadCaptureArmingDisposer) {
+        uploadCaptureArmingDisposer();
+        uploadCaptureArmingDisposer = null;
+      }
       if (evenAiEndpoint) {
         evenAiEndpoint.close();
       }
@@ -3184,7 +3555,6 @@ function createRelay(opts) {
 
     handleBufferedEvenAiHttpRequest,
 
-    /** The downstream server instance. */
     get server() {
       return server;
     },
@@ -3245,7 +3615,6 @@ function createRelay(opts) {
       return sessionService.getDisplayCurrentStates(sessionKey);
     },
 
-    // Accessors used by the session-title distiller sidecar.
     getSessionTitleRecord(sessionKey) {
       return sessionService.getSessionTitleRecord(sessionKey);
     },
@@ -3258,12 +3627,7 @@ function createRelay(opts) {
     getDistillerBudget() {
       return sessionService.getDistillerBudget();
     },
-    // Canonical-key cleanup for the distiller's throwaway upstream session.
-    // The native subagent deleteSession passes the bare key straight to
-    // sessions.delete, which the 2026.6.x gateway indexes under the canonical
-    // agent:<id>: form — the bare-key delete silently no-ops and the
-    // excerpt-bearing transcript survives. deleteSessions() resolves the
-    // canonical key via sessions.resolve first.
+
     deleteDistillerSession(sessionKey) {
       return sessionService.deleteSessions("ocuclaw", [sessionKey]);
     },
@@ -3284,11 +3648,6 @@ function createRelay(opts) {
       return sessionService.peekSessionKey();
     },
 
-    /**
-     * Test/shutdown hook: resolves once the async first-user-message cache
-     * write has fully drained (no write in flight, no dirty mark pending) so
-     * the on-disk file reflects the latest in-memory map.
-     */
     flushFirstSentUserMessageCache() {
       return sessionService.flushFirstSentUserMessageCache();
     },
@@ -3305,20 +3664,10 @@ function createRelay(opts) {
       return result;
     },
 
-    /**
-     * Test-only: direct access to dispatchOcuClawUserSend so integration
-     * tests can drive per-turn signal plumbing without a live downstream
-     * WebSocket connection.
-     */
     _dispatchOcuClawUserSend(params) {
       return dispatchOcuClawUserSend(params || {});
     },
 
-    /**
-     * Test-only: run the logical-reset state clear (the same call the /new,
-     * /reset, and new-chat paths make) so integration tests can verify all
-     * per-session state is dropped for a reused session key.
-     */
     _clearLogicalSessionState(sessionKey) {
       sessionService.clearLogicalSessionState(sessionKey);
     },
@@ -3331,6 +3680,39 @@ function createRelay(opts) {
       sendGlassesUiSurfaceUpdate(params);
     },
 
+    dispatchGlassesWake(params) {
+      const sessionKey =
+        params && typeof params.sessionKey === "string" && params.sessionKey
+          ? params.sessionKey
+          : sessionService.ensureSessionKey();
+      const message = params && typeof params.message === "string" ? params.message : "";
+      if (!message) {
+        return Promise.reject(new Error("dispatchGlassesWake requires a message"));
+      }
+      const idempotencyKey =
+        params && typeof params.idempotencyKey === "string" && params.idempotencyKey
+          ? params.idempotencyKey
+          : null;
+      agentTurnTracker.markBusy(sessionKey);
+      emitDebug(
+        "relay.protocol",
+        "glasses_wake_dispatch",
+        "info",
+        { sessionKey },
+        () => ({
+          idempotencyKey,
+          messageChars: message.length,
+        }),
+      );
+      const requestParams = { message, sessionKey };
+      if (idempotencyKey) requestParams.idempotencyKey = idempotencyKey;
+      return gatewayBridge.request("agent", requestParams, { expectFinal: false });
+    },
+
+    isAgentTurnBusy(sessionKey) {
+      return agentTurnTracker.isBusy(sessionKey);
+    },
+
     onGlassesUiResult(handler) {
       return onGlassesUiResult(handler);
     },
@@ -3351,6 +3733,10 @@ function createRelay(opts) {
       return server ? server.getConnectedAppCount() > 0 : false;
     },
 
+    isGlassesSendBufferOverHighWater() {
+      return glassesBackpressureLatch.isOverHighWater();
+    },
+
     onAppClientDisconnect(handler) {
       return onAppClientDisconnect(handler);
     },