ocuclaw 1.3.2 → 1.3.4

package/dist/runtime/downstream-handler.js

@@ -1,16 +1,18 @@
-import { normalizeEvenAiRoutingMode } from "../even-ai/even-ai-settings-store.js";
+import {
+  normalizeEvenAiRoutingMode,
+  normalizeEvenAiDefaultAgent,
+} from "../even-ai/even-ai-settings-store.js";
 import {
   normalizeOcuClawDefaultModel,
   normalizeOcuClawDefaultThinking,
   normalizeOcuClawSystemPrompt,
+  normalizeOcuClawDefaultAgent,
 } from "./ocuclaw-settings-store.js";
 import {
   formatMainOperationReceived,
   formatSendAck,
 } from "./relay-worker-protocol.js";
 
-// --- Factory ---
-
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
     return console;
@@ -24,61 +26,12 @@ function normalizeLogger(logger) {
   };
 }
 
-/**
- * Create a downstream message handler.
- *
- * Transport-agnostic protocol logic for processing messages from
- * downstream clients (Even App, commander.html). Consumed by relay.js.
- *
- * @param {object} opts
- * @param {(id: string, text: string, sessionKey: string|null, attachment: object|null, clientDisplaySignals: object|null) => Promise} opts.onSend
- *   Forward a user message to the upstream OpenClaw agent.
- * @param {(sender: string, text: string) => Array} opts.onSimulate
- *   Inject a fake message into conversation state; returns pages array.
-   * @param {(request: object) => Promise<object>|object} [opts.onSimulateStream]
-   *   Inject deterministic streaming payload (relay-local), then finalize pages.
- * @param {() => Promise<Array>} opts.onNewChat
- *   Clear conversation and reset the OpenClaw session; returns empty pages array.
- * @param {() => Promise<{models: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetModelsCatalog]
- *   Return cached model catalog snapshot.
- * @param {() => Promise<{skills: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetSkillsCatalog]
- *   Return cached skills catalog snapshot.
- * @param {() => Promise<{models: Array, fetchedAtMs: number, stale: boolean}>} [opts.onGetSonioxModels]
- *   Return cached Soniox model snapshot.
- * @param {() => Promise<object>} [opts.onGetProviderUsageSnapshot]
- *   Return the current provider usage snapshot for the active provider.
- * @param {() => Promise<object>} [opts.onGetSessionModelConfig]
- *   Return current session model controls.
- * @param {(patch: object) => Promise<{status: string, error?: string}>} [opts.onSetSessionModelConfig]
- *   Patch current session model controls.
- * @param {({sessionKey: string}) => Promise<{status: string, error?: string}>} [opts.onCompactSession]
- *   Trigger gateway-side compaction for a session key.
- * @param {() => Promise<object>} [opts.onGetEvenAiSettings]
- *   Return current relay-owned Even AI settings.
- * @param {() => Promise<{sessions: Array, dedicatedKey: string}>} [opts.onGetEvenAiSessions]
- *   Return the Even AI session-browser payload.
- * @param {(patch: object) => Promise<{status: string, error?: string, settings?: object}>} [opts.onSetEvenAiSettings]
- *   Patch relay-owned Even AI settings.
- * @param {() => Promise<object>} [opts.onGetOcuClawSettings]
- *   Return current relay-owned OcuClaw settings.
- * @param {(patch: object) => Promise<{status: string, error?: string, settings?: object}>} [opts.onSetOcuClawSettings]
- *   Patch relay-owned OcuClaw settings.
- * @param {(clientId: string, payload: object) => Promise<object>|object} [opts.onRequestSonioxTemporaryKey]
- *   Mint a short-lived Soniox temporary key for the provided voiceSessionId.
- * @param {() => object} [opts.onGetStatus]
- *   Return the current relay status snapshot.
- * @param {() => boolean} opts.isUpstreamConnected
- *   Returns true if the OpenClaw gateway connection is active.
- * @param {(clientId: string, payload: object) => void} [opts.onEventDebug]
- *   Optional structured client debug-event callback.
- * @param {(clientId: string, payload: object) => Promise<object>|object} [opts.onReadinessProbe]
- *   Optional dedicated readiness-probe dispatcher.
- * @returns {object} Handler instance
- */
 function createDownstreamHandler(opts) {
   const logger = normalizeLogger(opts.logger);
   const externalDebugToolsEnabled = opts.externalDebugToolsEnabled !== false;
   const onSend = opts.onSend;
+  const onAbortSession = opts.onAbortSession || null;
+  const onSteerSession = opts.onSteerSession || null;
   const onSimulate = opts.onSimulate;
   const onSimulateStream = opts.onSimulateStream || null;
   const onNewChat = opts.onNewChat;
@@ -88,10 +41,12 @@ function createDownstreamHandler(opts) {
   const onSlashCommand = opts.onSlashCommand;
   const onGetModelsCatalog = opts.onGetModelsCatalog;
   const onGetSkillsCatalog = opts.onGetSkillsCatalog;
+  const onGetAgentsCatalog = opts.onGetAgentsCatalog;
   const onGetSonioxModels = opts.onGetSonioxModels || null;
   const onGetProviderUsageSnapshot = opts.onGetProviderUsageSnapshot || null;
   const onGetSessionModelConfig = opts.onGetSessionModelConfig;
   const onSetSessionModelConfig = opts.onSetSessionModelConfig;
+  const onSetSessionAgent = opts.onSetSessionAgent;
   const onCompactSession = opts.onCompactSession || null;
   const onGetEvenAiSettings = opts.onGetEvenAiSettings;
   const onGetEvenAiSessions = opts.onGetEvenAiSessions;
@@ -99,6 +54,7 @@ function createDownstreamHandler(opts) {
   const onGetOcuClawSettings = opts.onGetOcuClawSettings;
   const onSetOcuClawSettings = opts.onSetOcuClawSettings;
   const onRequestSonioxTemporaryKey = opts.onRequestSonioxTemporaryKey || null;
+  const onRequestCartesiaAccessToken = opts.onRequestCartesiaAccessToken || null;
   const onGetStatus = opts.onGetStatus || null;
   const isUpstreamConnected = opts.isUpstreamConnected;
   const onConsoleLog = opts.onConsoleLog || null;
@@ -119,10 +75,12 @@ function createDownstreamHandler(opts) {
   const onSetSessionPinned = opts.onSetSessionPinned || null;
   const onDeleteSessions = opts.onDeleteSessions || null;
   const onSearchTranscripts = opts.onSearchTranscripts || null;
+  const onDebugBundleRequest = opts.onDebugBundleRequest || null;
+  const onDebugBundleSave = opts.onDebugBundleSave || null;
+  const onDebugBundleFetch = opts.onDebugBundleFetch || null;
   const getSnapshotRevision = opts.getSnapshotRevision || null;
   const operationRegistry = opts.operationRegistry || null;
 
-  /** Client IDs subscribed to raw protocol frame forwarding. */
   const protocolSubscribers = new Set();
   const APPROVAL_DECISIONS = new Set(["allow-once", "allow-always", "deny"]);
   const approvalResolveCacheTtlMs = Number.isFinite(opts.approvalResolveCacheTtlMs)
@@ -133,7 +91,7 @@ function createDownstreamHandler(opts) {
     : 500;
   const EXTERNAL_DEBUG_TOOLS_DISABLED_ERROR =
     "external debug tools are disabled by plugin config";
-  /** @type {Map<string, {expiresAtMs: number, promise: Promise<object>}>} */
+
   const approvalResolveCache = new Map();
   const APP_PROTOCOL = {
     activity: "ocuclaw.activity.update",
@@ -165,6 +123,8 @@ function createDownstreamHandler(opts) {
     providerUsageSnapshot: "ocuclaw.provider.usage.snapshot",
     skillsCatalogGet: "ocuclaw.skills.catalog.get",
     skillsCatalogSnapshot: "ocuclaw.skills.catalog.snapshot",
+    agentsCatalogGet: "ocuclaw.agent.catalog.get",
+    agentsCatalogSnapshot: "ocuclaw.agent.catalog.snapshot",
     pages: "ocuclaw.view.pages.snapshot",
     protocolSubscribe: "ocuclaw.protocol.tap.subscribe",
     protocolFrame: "ocuclaw.protocol.tap.frame",
@@ -172,37 +132,38 @@ function createDownstreamHandler(opts) {
     readinessProbeRequest: "ocuclaw.readiness.probe.request",
     remoteControl: "ocuclaw.remote.control",
     requestSonioxTemporaryKey: "requestSonioxTemporaryKey",
+    requestCartesiaAccessToken: "requestCartesiaAccessToken",
     sonioxModelsGet: "ocuclaw.voice.soniox.models.get",
     sonioxModelsSnapshot: "ocuclaw.voice.soniox.models.snapshot",
     sessionConfigGet: "ocuclaw.session.config.get",
     sessionConfigSet: "ocuclaw.session.config.set",
     sessionConfigSetAck: "ocuclaw.session.config.set.ack",
     sessionConfigSnapshot: "ocuclaw.session.config.snapshot",
+    sessionAgentSet: "ocuclaw.session.agent.set",
+    sessionAgentSetAck: "ocuclaw.session.agent.set.ack",
+    sessionAbort: "ocuclaw.session.abort",
+    sessionAbortAck: "ocuclaw.session.abort.ack",
     sessionCompact: "ocuclaw.session.compact",
     sessionCompactAck: "ocuclaw.session.compact.ack",
     sessionCreate: "ocuclaw.session.create",
     sessionList: "ocuclaw.session.list",
+    sessionListDiff: "ocuclaw.session.list.diff",
+    sessionListDiffResult: "ocuclaw.session.list.diff.result",
     sessionListResult: "ocuclaw.session.list.result",
     sessionReset: "ocuclaw.session.reset",
+    sessionSteer: "ocuclaw.session.steer",
     sessionSwitch: "ocuclaw.session.switch",
     sessionSwitchApplied: "ocuclaw.session.switch.applied",
     sessionTitleSet: "ocuclaw.session.title.set",
     sonioxTemporaryKey: "sonioxTemporaryKey",
     sonioxTemporaryKeyError: "sonioxTemporaryKeyError",
+    cartesiaAccessToken: "cartesiaAccessToken",
+    cartesiaAccessTokenError: "cartesiaAccessTokenError",
     status: "ocuclaw.runtime.status",
     statusGet: "ocuclaw.runtime.status.get",
     typingUpdate: "ocuclaw.typing.update",
   };
 
-  // --- Format helpers ---
-
-  /**
-   * Format a pages message for broadcast.
-   *
-   * @param {Array<{content: string, subPage: [number,number]|null}>} pages
-   * @param {{revision?: number}} [meta]
-   * @returns {string} JSON string
-   */
   function formatPages(pages, meta) {
     const msg = { type: APP_PROTOCOL.pages, pages };
     const fallbackRevision = getSnapshotRevision
@@ -219,13 +180,6 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(msg);
   }
 
-  /**
-   * Format a status message for broadcast.
-   *
-   * @param {object} status - Status fields (openclaw, agent, session, etc.)
-   * @param {{revision?: number}} [meta]
-   * @returns {string} JSON string
-   */
   function formatStatus(status, meta) {
     const msg = { ...status, type: APP_PROTOCOL.status };
     const fallbackRevision = getSnapshotRevision
@@ -242,33 +196,14 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(msg);
   }
 
-  /**
-   * Format an activity message for broadcast.
-   *
-   * @param {object} activity - Activity fields (state, tool, etc.)
-   * @returns {string} JSON string
-   */
   function formatActivity(activity) {
     return JSON.stringify({ ...activity, type: APP_PROTOCOL.activity });
   }
 
-  /**
-   * Format a typing update message for broadcast.
-   *
-   * @param {object} update - Typing fields (state, runId, sessionKey, etc.)
-   * @returns {string} JSON string
-   */
   function formatTyping(update) {
     return JSON.stringify({ ...update, type: APP_PROTOCOL.typingUpdate });
   }
 
-  /**
-   * Format an error message for unicast.
-   *
-   * @param {string} error
-   * @param {{code?: string, requestId?: string, op?: string}} [meta]
-   * @returns {string} JSON string
-   */
   function formatError(error, meta) {
     const msg = {
       type: "error",
@@ -301,30 +236,25 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Format a send acknowledgement for unicast.
-   *
-   * @param {string} id - Message ID being acknowledged
-   * @param {string} status - "accepted" or "rejected"
-   * @param {string} [error] - Error message (for rejected)
-   * @param {string} [errorCode] - Structured error code (for deterministic client handling)
-   * @returns {string} JSON string
-   */
-  function formatSendAckCompat(id, status, error, errorCode) {
-    return formatSendAck(id, status, error, errorCode);
+  function formatSendAckCompat(id, status, error, errorCode, data) {
+    return formatSendAck(id, status, error, errorCode, data);
+  }
+
+  function formatSessionAbortAck(data = {}) {
+    const msg = {
+      type: APP_PROTOCOL.sessionAbortAck,
+      requestId: parseOptionalTrimmedString(data.requestId),
+      status: data.status || "accepted",
+    };
+    if (data.error !== undefined) msg.error = data.error;
+    if (data.errorCode !== undefined) msg.errorCode = data.errorCode;
+    return JSON.stringify(msg);
   }
 
   function formatOperationReceived(data) {
     return formatMainOperationReceived(data);
   }
 
-  /**
-   * Format a protocol frame for forwarding to subscribers.
-   *
-   * @param {string} direction - "in" or "out"
-   * @param {object} frame - Raw protocol frame
-   * @returns {string} JSON string
-   */
   function formatProtocol(direction, frame) {
     return JSON.stringify({
       type: APP_PROTOCOL.protocolFrame,
@@ -333,13 +263,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a streaming text message for broadcast during agent runs.
-   *
-   * @param {string} text - Streaming assistant text
-   * @param {Array<{start: number, end: number, emoji: string}>} [spans] - Optional emoji spans
-   * @returns {string} JSON string
-   */
   function formatStreaming(text, emojiSpans, paceSpans) {
     const payload = { type: APP_PROTOCOL.messageStreamDelta, text };
     if (Array.isArray(emojiSpans) && emojiSpans.length > 0) {
@@ -351,22 +274,135 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(payload);
   }
 
-  /**
-   * Format a sessions list message for unicast response.
-   *
-   * @param {Array<{key: string, updatedAt: number, preview: string, firstUserMessage?: string}>} sessions
-   * @returns {string} JSON string
-   */
   function formatSessions(sessions) {
     return JSON.stringify({ type: APP_PROTOCOL.sessionListResult, sessions });
   }
 
-  /**
-   * Format a session-switched confirmation for broadcast.
-   *
-   * @param {string} sessionKey
-   * @returns {string} JSON string
-   */
+  function sessionInfoFingerprint(session) {
+    const row = session && typeof session === "object" ? session : {};
+    const raw = [
+      row.key || "",
+      Number.isFinite(Number(row.updatedAt)) ? String(Math.floor(Number(row.updatedAt))) : "0",
+      row.preview || "",
+      row.firstUserMessage || "",
+      row.title || "",
+      row.pinned === true ? "true" : "false",
+      Number.isFinite(Number(row.pinnedAtMs)) ? String(Math.floor(Number(row.pinnedAtMs))) : "",
+      row.agentId || "",
+      row.agentName || "",
+    ].join("\u001f");
+    return fnv1a32Hex(raw);
+  }
+
+  function fnv1a32Hex(text) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+      hash ^= text.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+  }
+
+  function normalizeSessionDiffLimit(limit) {
+    if (!Number.isFinite(Number(limit)) || Number(limit) <= 0) return 80;
+    return Math.min(200, Math.max(1, Math.floor(Number(limit))));
+  }
+
+  function normalizeSessionDiffKind(kind) {
+    return String(kind || "").trim().toLowerCase() === "evenai"
+      ? "evenai"
+      : "ocuclaw";
+  }
+
+  function parseKnownSessionRows(msg) {
+    if (!msg || !Array.isArray(msg.known)) return [];
+    const out = [];
+    for (const item of msg.known) {
+      if (!item || typeof item !== "object") continue;
+      const key = typeof item.key === "string" ? item.key.trim() : "";
+      if (!key) continue;
+      out.push({
+        key,
+        updatedAt: Number.isFinite(Number(item.updatedAt))
+          ? Math.floor(Number(item.updatedAt))
+          : 0,
+        fingerprint:
+          typeof item.fingerprint === "string" ? item.fingerprint.trim() : "",
+      });
+    }
+    return out;
+  }
+
+  function buildSessionDiff({ kind, sessions, known, limit, dedicatedKey }) {
+    const normalizedKind = normalizeSessionDiffKind(kind);
+    const normalizedLimit = normalizeSessionDiffLimit(limit);
+    const rows = Array.isArray(sessions) ? sessions : [];
+    const limitedRows = rows
+      .slice()
+      .sort((left, right) => (Number(right && right.updatedAt) || 0) - (Number(left && left.updatedAt) || 0))
+      .slice(0, normalizedLimit);
+    const knownByKey = new Map();
+    for (const row of Array.isArray(known) ? known : []) {
+      const key = typeof row.key === "string" ? row.key.trim().toLowerCase() : "";
+      if (!key) continue;
+      knownByKey.set(key, row);
+    }
+    const liveKeys = new Set();
+    const changed = [];
+    for (const row of limitedRows) {
+      const key = typeof row.key === "string" ? row.key.trim().toLowerCase() : "";
+      if (!key) continue;
+      liveKeys.add(key);
+      const knownRow = knownByKey.get(key);
+      const updatedAt = Number.isFinite(Number(row.updatedAt))
+        ? Math.floor(Number(row.updatedAt))
+        : 0;
+      const fingerprint = sessionInfoFingerprint(row);
+      if (
+        !knownRow ||
+        knownRow.updatedAt !== updatedAt ||
+        knownRow.fingerprint !== fingerprint
+      ) {
+        changed.push(row);
+      }
+    }
+    const deletedKeys = [];
+    for (const row of Array.isArray(known) ? known : []) {
+      const rawKey = typeof row.key === "string" ? row.key.trim() : "";
+      const key = rawKey.toLowerCase();
+      if (key && !liveKeys.has(key)) deletedKeys.push(rawKey);
+    }
+    const out = {
+      type: APP_PROTOCOL.sessionListDiffResult,
+      kind: normalizedKind,
+      sessions: changed,
+      deletedKeys,
+      limit: normalizedLimit,
+    };
+    if (typeof dedicatedKey === "string" && dedicatedKey) {
+      out.dedicatedKey = dedicatedKey;
+    }
+    return out;
+  }
+
+  function formatSessionDiff(payload) {
+    return JSON.stringify(buildSessionDiff(payload || {}));
+  }
+
+  function formatEmptySessionDiff(kind, limit, dedicatedKey) {
+    const out = {
+      type: APP_PROTOCOL.sessionListDiffResult,
+      kind: normalizeSessionDiffKind(kind),
+      sessions: [],
+      deletedKeys: [],
+      limit: normalizeSessionDiffLimit(limit),
+    };
+    if (typeof dedicatedKey === "string" && dedicatedKey) {
+      out.dedicatedKey = dedicatedKey;
+    }
+    return JSON.stringify(out);
+  }
+
   function formatSessionSwitched(sessionKey) {
     return JSON.stringify({
       type: APP_PROTOCOL.sessionSwitchApplied,
@@ -374,12 +410,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a model catalog snapshot for unicast.
-   *
-   * @param {{models: Array, fetchedAtMs: number, stale: boolean}} payload
-   * @returns {string}
-   */
   function formatModelsCatalog(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.modelCatalogSnapshot,
@@ -392,12 +422,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a cached skills catalog snapshot for unicast.
-   *
-   * @param {{skills?: Array, fetchedAtMs?: number, stale?: boolean}} payload
-   * @returns {string}
-   */
   function formatSkillsCatalog(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.skillsCatalogSnapshot,
@@ -410,12 +434,27 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a Soniox model snapshot for unicast.
-   *
-   * @param {{models: Array, fetchedAtMs: number, stale: boolean}} payload
-   * @returns {string}
-   */
+  function formatAgentsCatalog(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.agentsCatalogSnapshot,
+      agents: Array.isArray(payload && payload.agents) ? payload.agents : [],
+      defaultId:
+        payload && typeof payload.defaultId === "string"
+          ? payload.defaultId
+          : null,
+      mainKey:
+        payload && typeof payload.mainKey === "string" ? payload.mainKey : null,
+      scope:
+        payload && typeof payload.scope === "string" ? payload.scope : null,
+      fetchedAtMs:
+        Number.isFinite(payload && payload.fetchedAtMs)
+          ? Math.floor(payload.fetchedAtMs)
+          : Date.now(),
+      stale: !!(payload && payload.stale),
+      unsupported: !!(payload && payload.unsupported),
+    });
+  }
+
   function formatSonioxModels(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.sonioxModelsSnapshot,
@@ -428,12 +467,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a provider usage snapshot for unicast.
-   *
-   * @param {object} payload
-   * @returns {string}
-   */
   function formatProviderUsageSnapshot(payload) {
     const provider =
       payload && typeof payload.provider === "string" && payload.provider.trim()
@@ -497,12 +530,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format current session model controls.
-   *
-   * @param {object} payload
-   * @returns {string}
-   */
   function formatSessionModelConfig(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.sessionConfigSnapshot,
@@ -530,15 +557,11 @@ function createDownstreamHandler(opts) {
         payload && typeof payload.elevatedLevel === "string"
           ? payload.elevatedLevel
           : "off",
+      agentId:
+        payload && typeof payload.agentId === "string" ? payload.agentId : "",
     });
   }
 
-  /**
-   * Format a session model config write acknowledgement.
-   *
-   * @param {{status: string, error?: string}} payload
-   * @returns {string}
-   */
   function formatSessionModelConfigAck(payload) {
     const out = {
       type: APP_PROTOCOL.sessionConfigSetAck,
@@ -553,12 +576,6 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(out);
   }
 
-  /**
-   * Format a compactSession ack message for unicast.
-   *
-   * @param {{status: string, error?: string, requestId?: string}} payload
-   * @returns {string} JSON string
-   */
   function formatCompactSessionAck(payload) {
     const msg = {
       type: APP_PROTOCOL.sessionCompactAck,
@@ -577,12 +594,6 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(msg);
   }
 
-  /**
-   * Format the current relay-owned Even AI settings snapshot.
-   *
-   * @param {object} payload
-   * @returns {string}
-   */
   function formatEvenAiSettings(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.evenAiSettingsSnapshot,
@@ -605,15 +616,14 @@ function createDownstreamHandler(opts) {
           : "",
       listenEnabled: payload && payload.listenEnabled === true,
       defaultFastMode: !!(payload && payload.defaultFastMode === true),
+      defaultAgent: normalizeEvenAiDefaultAgent(
+        payload && typeof payload.defaultAgent === "string"
+          ? payload.defaultAgent
+          : undefined,
+      ),
     });
   }
 
-  /**
-   * Format an Even AI settings write acknowledgement.
-   *
-   * @param {{status: string, error?: string}} payload
-   * @returns {string}
-   */
   function formatEvenAiSettingsAck(payload) {
     const out = {
       type: APP_PROTOCOL.evenAiSettingsSetAck,
@@ -628,12 +638,6 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(out);
   }
 
-  /**
-   * Format the current relay-owned OcuClaw settings snapshot.
-   *
-   * @param {object} payload
-   * @returns {string}
-   */
   function formatOcuClawSettings(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.ocuClawSettingsSnapshot,
@@ -653,15 +657,14 @@ function createDownstreamHandler(opts) {
           : undefined,
       ),
       defaultFastMode: !!(payload && payload.defaultFastMode === true),
+      defaultAgent: normalizeOcuClawDefaultAgent(
+        payload && typeof payload.defaultAgent === "string"
+          ? payload.defaultAgent
+          : undefined,
+      ),
     });
   }
 
-  /**
-   * Format an OcuClaw settings write acknowledgement.
-   *
-   * @param {{status: string, error?: string}} payload
-   * @returns {string}
-   */
   function formatOcuClawSettingsAck(payload) {
     const out = {
       type: APP_PROTOCOL.ocuClawSettingsSetAck,
@@ -676,12 +679,6 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(out);
   }
 
-  /**
-   * Format the Even AI session-browser result payload.
-   *
-   * @param {{sessions?: Array, dedicatedKey?: string}} payload
-   * @returns {string}
-   */
   function formatEvenAiSessions(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.evenAiSessionListResult,
@@ -693,12 +690,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format an exec approval request for broadcast.
-   *
-   * @param {object} data - Approval payload from gateway
-   * @returns {string} JSON string
-   */
   function formatApproval(data) {
     const request = data && data.request ? data.request : {};
     const approvalKind =
@@ -750,12 +741,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format an exec approval resolution for broadcast.
-   *
-   * @param {object} data - Resolution payload from gateway
-   * @returns {string} JSON string
-   */
   function formatApprovalResolved(data) {
     return JSON.stringify({
       type: APP_PROTOCOL.approvalResolved,
@@ -768,12 +753,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format an approval-response acknowledgement for unicast.
-   *
-   * @param {object} data
-   * @returns {string}
-   */
   function formatApprovalResponseAck(data) {
     return JSON.stringify({
       type: APP_PROTOCOL.approvalResolveAck,
@@ -802,14 +781,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a committed listen handoff update for broadcast during voice mode.
-   *
-   * @param {string} text - Final committed text sent upstream
-   * @param {"manual"|"endpoint"} source - Commit source path
-   * @param {string|null} sessionKey - Active relay session key for diagnostics
-   * @returns {string} JSON string
-   */
   function formatListenCommitted(text, source, sessionKey) {
     return JSON.stringify({
       type: "listen-committed",
@@ -826,20 +797,10 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a listen-ended message for broadcast.
-   * @returns {string} JSON string
-   */
   function formatListenEnded() {
     return JSON.stringify({ type: "listen-ended" });
   }
 
-  /**
-   * Format a listen-error message for broadcast.
-   * @param {string} error - Error description
-   * @param {string|null} [code] - Structured error code
-   * @returns {string} JSON string
-   */
   function formatListenError(error, code = null) {
     const msg = { type: "listen-error", error };
     if (typeof code === "string" && code.trim()) {
@@ -848,20 +809,10 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(msg);
   }
 
-  /**
-   * Format a listen-ready message for broadcast (agent done, client can auto-restart).
-   * @returns {string} JSON string
-   */
   function formatListenReady() {
     return JSON.stringify({ type: "listen-ready" });
   }
 
-  /**
-   * Format a temporary Soniox key lease for unicast back to the requesting client.
-   *
-   * @param {{voiceSessionId: string, temporaryKey: string, expiresAtMs: number}} payload
-   * @returns {string}
-   */
   function formatSonioxTemporaryKey(payload) {
     return JSON.stringify({
       type: APP_PROTOCOL.sonioxTemporaryKey,
@@ -880,12 +831,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a Soniox temporary-key failure for unicast back to the requesting client.
-   *
-   * @param {{voiceSessionId: string, error: string, code?: string|null}} payload
-   * @returns {string}
-   */
   function formatSonioxTemporaryKeyError(payload) {
     const msg = {
       type: APP_PROTOCOL.sonioxTemporaryKeyError,
@@ -908,6 +853,88 @@ function createDownstreamHandler(opts) {
     return JSON.stringify(msg);
   }
 
+  function parseRequestCartesiaAccessToken(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("requestCartesiaAccessToken payload must be an object");
+    }
+
+    const voiceSessionId = parseOptionalTrimmedString(msg.voiceSessionId);
+    if (!voiceSessionId) {
+      throw new Error("voiceSessionId is required");
+    }
+
+    return {
+      voiceSessionId,
+      sessionKey: parseOptionalTrimmedString(msg.sessionKey),
+    };
+  }
+
+  function normalizeCartesiaAccessTokenErrorCode(err) {
+
+    const explicit = err && typeof err.code === "string" ? err.code.trim() : "";
+    if (explicit) return explicit;
+
+    const message =
+      err && typeof err.message === "string" && err.message.trim()
+        ? err.message.trim()
+        : "";
+    const lowered = message.toLowerCase();
+    if (!message) return "cartesia_access_token_failed";
+
+    if (err && err.name === "AbortError") {
+      return "cartesia_access_token_mint_timeout";
+    }
+    if (lowered.includes("api key is not configured")) {
+      return "cartesia_access_token_not_configured";
+    }
+    if (lowered.includes("fetch is not available")) {
+      return "cartesia_access_token_fetch_unavailable";
+    }
+    if (lowered.includes("voicesessionid is required")) {
+      return "cartesia_access_token_invalid_request";
+    }
+    if (lowered.includes("missing token")) {
+      return "cartesia_access_token_invalid_response";
+    }
+    const statusMatch = lowered.match(/\((\d{3})\)/);
+    if (statusMatch) {
+      return `cartesia_access_token_http_${statusMatch[1]}`;
+    }
+    return "cartesia_access_token_failed";
+  }
+
+  function formatCartesiaAccessToken(payload) {
+    return JSON.stringify({
+      type: APP_PROTOCOL.cartesiaAccessToken,
+      voiceSessionId:
+        payload && typeof payload.voiceSessionId === "string" ? payload.voiceSessionId : "",
+      accessToken:
+        payload && typeof payload.accessToken === "string" ? payload.accessToken : "",
+      expiresAtMs:
+        payload && Number.isFinite(payload.expiresAtMs) ? Math.floor(payload.expiresAtMs) : 0,
+    });
+  }
+
+  function formatCartesiaAccessTokenError(payload) {
+    const msg = {
+      type: APP_PROTOCOL.cartesiaAccessTokenError,
+      voiceSessionId:
+        payload && typeof payload.voiceSessionId === "string" ? payload.voiceSessionId : "",
+      error:
+        payload && typeof payload.error === "string" && payload.error.trim()
+          ? payload.error.trim()
+          : "Cartesia access-token request failed",
+    };
+    const code =
+      payload && typeof payload.code === "string" && payload.code.trim()
+        ? payload.code.trim()
+        : "";
+    if (code) {
+      msg.code = code;
+    }
+    return JSON.stringify(msg);
+  }
+
   function normalizeSonioxTemporaryKeyErrorCode(err) {
     const message =
       err && typeof err.message === "string" && err.message.trim()
@@ -915,7 +942,7 @@ function createDownstreamHandler(opts) {
         : "";
     const lowered = message.toLowerCase();
     if (!message) return "soniox_temp_key_request_failed";
-    // AbortError from the per-fetch timeout AbortController in mintSonioxTemporaryKey.
+
     if (err && err.name === "AbortError") {
       return "soniox_temp_key_mint_timeout";
     }
@@ -941,12 +968,6 @@ function createDownstreamHandler(opts) {
     return "soniox_temp_key_request_failed";
   }
 
-  /**
-   * Format a debug-set response for unicast.
-   *
-   * @param {object} data
-   * @returns {string}
-   */
   function formatDebugSet(data) {
     return JSON.stringify({
       type: "debug-set",
@@ -954,12 +975,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a debug-dump response for unicast.
-   *
-   * @param {object} data
-   * @returns {string}
-   */
   function formatDebugDump(data) {
     return JSON.stringify({
       type: "debug-dump",
@@ -967,10 +982,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Parse a "trace-log-set" message.
-   * @returns {{enabled: boolean}}
-   */
   function parseTraceLogSet(msg) {
     if (!msg || typeof msg !== "object") {
       throw new Error("trace-log-set requires an object");
@@ -981,19 +992,10 @@ function createDownstreamHandler(opts) {
     return { enabled: msg.enabled };
   }
 
-  /**
-   * Format a trace-log response for unicast (set + get share one type).
-   */
   function formatTraceLog(data) {
     return JSON.stringify({ type: "trace-log", ...data });
   }
 
-  /**
-   * Format the current relay debug-config snapshot for app/WebUI clients.
-   *
-   * @param {{serverNowMs: number, enabled: Array<{cat: string, expiresAtMs: number}>}} data
-   * @returns {string}
-   */
   function formatDebugConfigSnapshot(data) {
     const enabled = Array.isArray(data && data.enabled)
       ? data.enabled
@@ -1019,12 +1021,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a remote-control command for broadcast to app clients.
-   *
-   * @param {object} data
-   * @returns {string}
-   */
   function formatRemoteControl(data) {
     return JSON.stringify({
       type: APP_PROTOCOL.remoteControl,
@@ -1032,12 +1028,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Format a remote-control acknowledgement for unicast.
-   *
-   * @param {object} data
-   * @returns {string}
-   */
   function formatRemoteControlAck(data) {
     return JSON.stringify({
       type: "remote-control-ack",
@@ -1626,6 +1616,13 @@ function createDownstreamHandler(opts) {
       payload.defaultFastMode = msg.defaultFastMode;
     }
 
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultAgent")) {
+      if (typeof msg.defaultAgent !== "string") {
+        throw new Error("defaultAgent must be a string");
+      }
+      payload.defaultAgent = normalizeEvenAiDefaultAgent(msg.defaultAgent);
+    }
+
     if (Object.keys(payload).length === 0) {
       throw new Error("setEvenAiSettings requires at least one field");
     }
@@ -1668,6 +1665,13 @@ function createDownstreamHandler(opts) {
       payload.defaultFastMode = msg.defaultFastMode;
     }
 
+    if (Object.prototype.hasOwnProperty.call(msg, "defaultAgent")) {
+      if (typeof msg.defaultAgent !== "string") {
+        throw new Error("defaultAgent must be a string");
+      }
+      payload.defaultAgent = normalizeOcuClawDefaultAgent(msg.defaultAgent);
+    }
+
     if (Object.keys(payload).length === 0) {
       throw new Error("setOcuClawSettings requires at least one field");
     }
@@ -2006,11 +2010,6 @@ function createDownstreamHandler(opts) {
     };
   }
 
-  /**
-   * Validate and normalize an inbound clientDisplaySignals envelope.
-   * Returns null if absent or unparseable. Falls back to safe defaults
-   * for individual fields rather than rejecting the whole envelope.
-   */
   function parseClientDisplaySignals(raw) {
     if (raw == null || typeof raw !== "object") return null;
     const coerceState = (val) => {
@@ -2024,7 +2023,7 @@ function createDownstreamHandler(opts) {
     const enabledRaw = raw.neuralSessionNamesEnabled;
     const neuralSessionNamesEnabled =
       typeof enabledRaw === "boolean" ? enabledRaw : true;
-    // readSpeedWpm tolerated but ignored on inbound for old clients.
+
     return {
       neuralEmojiReactorState: state,
       neuralPaceModulatorState: paceState,
@@ -2032,15 +2031,6 @@ function createDownstreamHandler(opts) {
     };
   }
 
-  // --- Message handlers ---
-
-  /**
-   * Handle a "send" message: forward user text to upstream agent.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with id, text, sessionKey, and optional attachment
-   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
-   */
   function handleSend(clientId, msg) {
     const requestId = parseOptionalTrimmedString(msg.requestId);
     if (!requestId) {
@@ -2076,7 +2066,6 @@ function createDownstreamHandler(opts) {
       };
     }
 
-    // Check upstream connectivity
     if (!isUpstreamConnected()) {
       return {
         unicast: formatSendAckCompat(
@@ -2105,7 +2094,6 @@ function createDownstreamHandler(opts) {
 
     const clientDisplaySignals = parseClientDisplaySignals(msg.clientDisplaySignals);
 
-    // Forward to upstream — resolves on initial ack (accepted/queued)
     const followup = onSend(
       requestId,
       text,
@@ -2115,9 +2103,18 @@ function createDownstreamHandler(opts) {
     ).then(
       (result) => {
         const status = (result && result.status) || "accepted";
-        const frame = formatSendAckCompat(requestId, status);
+        const frame = formatSendAckCompat(
+          requestId,
+          status,
+          undefined,
+          undefined,
+          { runId: result && result.runId },
+        );
         if (operation && typeof operation.complete === "function") {
-          operation.complete(frame, { status });
+          operation.complete(frame, {
+            status,
+            runId: result && result.runId ? result.runId : null,
+          });
         }
         return { unicast: frame };
       },
@@ -2149,13 +2146,149 @@ function createDownstreamHandler(opts) {
       : followup;
   }
 
-  /**
-   * Handle a "simulate" message: inject fake message into conversation state.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with sender, text
-   * @returns {{ broadcast: string }}
-   */
+  function handleAbortSession(clientId, msg) {
+    const requestId = parseOptionalTrimmedString(msg.requestId);
+    if (!requestId) {
+      return {
+        unicast: formatSessionAbortAck({
+          requestId,
+          status: "rejected",
+          error: "Missing required field: requestId",
+        }),
+      };
+    }
+    const sessionKey = parseOptionalTrimmedString(msg.sessionKey);
+    if (!sessionKey) {
+      return {
+        unicast: formatSessionAbortAck({
+          requestId,
+          status: "rejected",
+          error: "Missing required field: sessionKey",
+        }),
+      };
+    }
+    if (!onAbortSession) {
+      return {
+        unicast: formatSessionAbortAck({
+          requestId,
+          status: "rejected",
+          error: "session abort is not available",
+        }),
+      };
+    }
+    if (!isUpstreamConnected()) {
+      return {
+        unicast: formatSessionAbortAck({
+          requestId,
+          status: "rejected",
+          error: "OpenClaw disconnected",
+        }),
+      };
+    }
+    return Promise.resolve(onAbortSession({ requestId, sessionKey })).then(
+      (result) => ({
+        unicast: formatSessionAbortAck({
+          requestId,
+          ...(result || { status: "accepted" }),
+        }),
+      }),
+      (err) => ({
+        unicast: formatSessionAbortAck({
+          requestId,
+          status: "rejected",
+          error: err && err.message ? err.message : "session abort failed",
+          errorCode: err && (err.errorCode || err.code) ? (err.errorCode || err.code) : undefined,
+        }),
+      }),
+    );
+  }
+
+  function handleSteerSession(clientId, msg) {
+    const requestId = parseOptionalTrimmedString(msg.requestId);
+    if (!requestId) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          "Missing required field: requestId",
+        ),
+      };
+    }
+    const sessionKey = parseOptionalTrimmedString(msg.sessionKey);
+    if (!sessionKey) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          "Missing required field: sessionKey",
+        ),
+      };
+    }
+    const parsedAttachment = parseAttachment(msg.attachment);
+    if (!parsedAttachment.ok) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          parsedAttachment.error,
+          parsedAttachment.errorCode,
+        ),
+      };
+    }
+    const message = typeof msg.message === "string" ? msg.message : "";
+    if (!message.trim() && !parsedAttachment.attachment) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          "Missing required field: message",
+        ),
+      };
+    }
+    if (!onSteerSession) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          "session steer is not available",
+        ),
+      };
+    }
+    if (!isUpstreamConnected()) {
+      return {
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          "OpenClaw disconnected",
+        ),
+      };
+    }
+    return Promise.resolve(onSteerSession({
+      requestId,
+      sessionKey,
+      message,
+      attachment: parsedAttachment.attachment,
+    })).then(
+      (result) => ({
+        unicast: formatSendAckCompat(
+          requestId,
+          (result && result.status) || "accepted",
+          undefined,
+          undefined,
+          { runId: result && result.runId },
+        ),
+      }),
+      (err) => ({
+        unicast: formatSendAckCompat(
+          requestId,
+          "rejected",
+          err && err.message ? err.message : "session steer failed",
+          err && (err.errorCode || err.code) ? (err.errorCode || err.code) : undefined,
+        ),
+      }),
+    );
+  }
+
   function handleSimulate(clientId, msg) {
     const pages = onSimulate(
       msg.sender || "Simulator",
@@ -2164,13 +2297,6 @@ function createDownstreamHandler(opts) {
     return { broadcast: formatPages(pages) };
   }
 
-  /**
-   * Handle a "simulateStream" message: relay-local deterministic stream replay.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with id, text, sender, and timing controls.
-   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
-   */
   function handleSimulateStream(clientId, msg) {
     const id = parseOptionalTrimmedString(msg.id);
     if (!id) {
@@ -2250,24 +2376,11 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "subscribeProtocol" message: mark client for protocol forwarding.
-   *
-   * @param {string} clientId
-   * @returns {null}
-   */
   function handleSubscribeProtocol(clientId) {
     protocolSubscribers.add(clientId);
     return null;
   }
 
-  /**
-   * Handle an "approvalResponse" message: forward decision to upstream gateway.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with id and decision
-   * @returns {{ unicast: string }|Promise<{ unicast: string }>}
-   */
   function handleApprovalResponse(clientId, msg) {
     let payload;
     try {
@@ -2373,12 +2486,6 @@ function createDownstreamHandler(opts) {
     });
   }
 
-  /**
-   * Handle a "newChat" message: clear conversation and reset the session.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ broadcast: string }>}
-   */
   function handleNewChat(clientId) {
     return onNewChat().then(
       (pages) => ({ broadcast: formatPages(pages) }),
@@ -2389,12 +2496,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "getSessions" message: fetch session list from upstream.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>}
-   */
   function handleGetSessions(clientId) {
     return onGetSessions().then(
       (sessions) => ({ unicast: formatSessions(sessions) }),
@@ -2405,12 +2506,46 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getModelsCatalog": return cached model catalog snapshot.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
+  function handleGetSessionDiff(clientId, msg) {
+    const kind = normalizeSessionDiffKind(msg && msg.kind);
+    const known = parseKnownSessionRows(msg);
+    const limit = normalizeSessionDiffLimit(msg && msg.limit);
+    if (kind === "evenai") {
+      if (!onGetEvenAiSessions) {
+        return Promise.resolve({
+          unicast: formatEmptySessionDiff(kind, limit, "ocuclaw:even-ai"),
+        });
+      }
+      return Promise.resolve(onGetEvenAiSessions()).then(
+        (payload) => ({
+          unicast: formatSessionDiff({
+            kind,
+            sessions: payload && payload.sessions,
+            known,
+            limit,
+            dedicatedKey:
+              payload && typeof payload.dedicatedKey === "string"
+                ? payload.dedicatedKey
+                : "ocuclaw:even-ai",
+          }),
+        }),
+        (err) => {
+          logger.error(`[downstream] getEvenAiSessionDiff failed: ${err.message}`);
+          return { unicast: formatEmptySessionDiff(kind, limit, "ocuclaw:even-ai") };
+        },
+      );
+    }
+    return onGetSessions().then(
+      (sessions) => ({
+        unicast: formatSessionDiff({ kind, sessions, known, limit }),
+      }),
+      (err) => {
+        logger.error(`[downstream] getSessionDiff failed: ${err.message}`);
+        return { unicast: formatEmptySessionDiff(kind, limit) };
+      },
+    );
+  }
+
   function handleGetModelsCatalog(clientId) {
     if (!onGetModelsCatalog) {
       return {
@@ -2438,12 +2573,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getSkills": return cached skills catalog snapshot.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetSkillsCatalog(clientId) {
     if (!onGetSkillsCatalog) {
       return {
@@ -2471,12 +2600,34 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getSonioxModels": return cached Soniox model snapshot.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
+  function handleGetAgentsCatalog(clientId) {
+    if (!onGetAgentsCatalog) {
+      return {
+        unicast: formatAgentsCatalog({
+          agents: [],
+          fetchedAtMs: Date.now(),
+          stale: true,
+          unsupported: true,
+        }),
+      };
+    }
+    return Promise.resolve(onGetAgentsCatalog()).then(
+      (payload) => ({
+        unicast: formatAgentsCatalog(payload || {}),
+      }),
+      (err) => {
+        logger.error(`[downstream] getAgentsCatalog failed: ${err.message}`);
+        return {
+          unicast: formatAgentsCatalog({
+            agents: [],
+            fetchedAtMs: Date.now(),
+            stale: true,
+          }),
+        };
+      },
+    );
+  }
+
   function handleGetSonioxModels(clientId) {
     if (!onGetSonioxModels) {
       return {
@@ -2504,12 +2655,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getProviderUsageSnapshot": return the current provider usage snapshot.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetProviderUsageSnapshot(clientId) {
     const emptySnapshot = () => ({
       sessionKey: null,
@@ -2539,12 +2684,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getStatus": return the current status snapshot.
-   *
-   * @param {string} clientId
-   * @returns {{ unicast: string }}
-   */
   function handleGetStatus(clientId) {
     if (!onGetStatus) {
       return { unicast: formatError("getStatus is not available") };
@@ -2558,12 +2697,6 @@ function createDownstreamHandler(opts) {
     }
   }
 
-  /**
-   * Handle "getSessionModelConfig": read controls for current session key.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetSessionModelConfig(clientId) {
     if (!onGetSessionModelConfig) {
       return { unicast: formatError("getSessionModelConfig is not available") };
@@ -2579,13 +2712,66 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "setSessionModelConfig": patch controls for current session key.
-   *
-   * @param {string} clientId
-   * @param {object} msg
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
+  function formatSessionAgentAck(payload) {
+    const out = {
+      type: APP_PROTOCOL.sessionAgentSetAck,
+      status:
+        payload && typeof payload.status === "string"
+          ? payload.status
+          : "rejected",
+    };
+    if (payload && payload.error !== undefined) {
+      out.error = payload.error;
+    }
+    return JSON.stringify(out);
+  }
+
+  function parseSetSessionAgent(msg) {
+    if (!msg || typeof msg !== "object") {
+      throw new Error("setSessionAgent payload must be an object");
+    }
+    if (!Object.prototype.hasOwnProperty.call(msg, "agentId")) {
+      throw new Error("setSessionAgent requires an agentId field");
+    }
+    if (msg.agentId !== null && typeof msg.agentId !== "string") {
+      throw new Error("agentId must be a string or null");
+    }
+    return { agentId: typeof msg.agentId === "string" ? msg.agentId.trim() : "" };
+  }
+
+  function handleSetSessionAgent(clientId, msg) {
+    if (!onSetSessionAgent) {
+      return {
+        unicast: formatSessionAgentAck({
+          status: "rejected",
+          error: "setSessionAgent is not available",
+        }),
+      };
+    }
+    let payload;
+    try {
+      payload = parseSetSessionAgent(msg);
+    } catch (err) {
+      return {
+        unicast: formatSessionAgentAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "invalid setSessionAgent payload",
+        }),
+      };
+    }
+    return Promise.resolve(onSetSessionAgent(payload)).then(
+      (result) => ({
+        unicast: formatSessionAgentAck(result || { status: "accepted" }),
+      }),
+      (err) => ({
+        unicast: formatSessionAgentAck({
+          status: "rejected",
+          error: err && err.message ? err.message : "setSessionAgent failed",
+        }),
+      }),
+    );
+  }
+
   function handleSetSessionModelConfig(clientId, msg) {
     if (!onSetSessionModelConfig) {
       return {
@@ -2623,13 +2809,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "compactSession": trigger gateway-side compaction for a session key.
-   *
-   * @param {string} clientId
-   * @param {object} msg - { sessionKey, requestId }
-   * @returns {Promise<{ unicast: string }>}
-   */
   function handleCompactSession(clientId, msg) {
     if (!onCompactSession) {
       return Promise.resolve({
@@ -2670,12 +2849,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getEvenAiSettings": read relay-owned Even AI settings.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetEvenAiSettings(clientId) {
     if (!onGetEvenAiSettings) {
       return { unicast: formatError("getEvenAiSettings is not available") };
@@ -2691,12 +2864,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getEvenAiSessions": return tracked Even AI sessions.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetEvenAiSessions(clientId) {
     if (!onGetEvenAiSessions) {
       return { unicast: formatError("getEvenAiSessions is not available") };
@@ -2712,13 +2879,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "setEvenAiSettings": patch relay-owned Even AI settings.
-   *
-   * @param {string} clientId
-   * @param {object} msg
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleSetEvenAiSettings(clientId, msg) {
     if (!onSetEvenAiSettings) {
       return {
@@ -2754,12 +2914,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "getOcuClawSettings": read relay-owned OcuClaw settings.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleGetOcuClawSettings(clientId) {
     if (!onGetOcuClawSettings) {
       return { unicast: formatError("getOcuClawSettings is not available") };
@@ -2775,13 +2929,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle "setOcuClawSettings": patch relay-owned OcuClaw settings.
-   *
-   * @param {string} clientId
-   * @param {object} msg
-   * @returns {Promise<{ unicast: string }>|{ unicast: string }}
-   */
   function handleSetOcuClawSettings(clientId, msg) {
     if (!onSetOcuClawSettings) {
       return {
@@ -2817,13 +2964,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "switchSession" message: switch to a different session.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with sessionKey
-   * @returns {Promise<{ broadcast: string[] }|null>}
-   */
   function handleSwitchSession(clientId, msg) {
     if (!msg.sessionKey) return null;
     return onSwitchSession(msg.sessionKey).then(
@@ -2840,12 +2980,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "newSession" message: create a new session.
-   *
-   * @param {string} clientId
-   * @returns {Promise<{ broadcast: string[] }|null>}
-   */
   function handleNewSession(clientId) {
     return onNewSession().then(
       (result) => {
@@ -2865,14 +2999,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "session.title.set" message: user-edited session title from
-   * phone UI. Sticky-locks the agent against retitling.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with sessionKey and title
-   * @returns {null}
-   */
   function handleSetUserSessionTitle(clientId, msg) {
     if (typeof onSetUserSessionTitle !== "function") return null;
     const sessionKey =
@@ -2924,13 +3050,6 @@ function createDownstreamHandler(opts) {
     return null;
   }
 
-  /**
-   * Handle a "slashCommand" message: forward a slash command to OpenClaw.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with command
-   * @returns {Promise<null>}
-   */
   function handleSlashCommand(clientId, msg) {
     if (!msg.command) return null;
     return onSlashCommand(msg.command).then(
@@ -2942,13 +3061,6 @@ function createDownstreamHandler(opts) {
     );
   }
 
-  /**
-   * Handle a "console" message: forward browser console output to log.
-   *
-   * @param {string} clientId
-   * @param {object} msg - Parsed message with level, message
-   * @returns {null}
-   */
   function handleConsole(clientId, msg) {
     if (onConsoleLog) {
       onConsoleLog(msg.level || "log", msg.message || "");
@@ -2956,11 +3068,6 @@ function createDownstreamHandler(opts) {
     return null;
   }
 
-  /**
-   * Handle a structured "eventDebug" message.
-   *
-   * Legacy payloads (without cat/event) fall back to onConsoleLog.
-   */
   function handleEventDebug(clientId, msg) {
     const parsed = parseEventDebug(msg);
     if (parsed && onEventDebug) {
@@ -2983,9 +3090,6 @@ function createDownstreamHandler(opts) {
     };
   }
 
-  /**
-   * Handle a "requestSonioxTemporaryKey" message.
-   */
   function handleRequestSonioxTemporaryKey(clientId, msg) {
     let payload;
     try {
@@ -3043,9 +3147,57 @@ function createDownstreamHandler(opts) {
     }
   }
 
-  /**
-   * Handle a "debug-set" message: enable/disable debug categories with TTL.
-   */
+  function handleRequestCartesiaAccessToken(clientId, msg) {
+    let payload;
+    try {
+      payload = parseRequestCartesiaAccessToken(msg);
+    } catch (err) {
+      return {
+        unicast: formatCartesiaAccessTokenError({
+          voiceSessionId:
+            msg && typeof msg.voiceSessionId === "string" ? msg.voiceSessionId : "",
+          error: err && err.message ? err.message : "requestCartesiaAccessToken failed",
+          code: normalizeCartesiaAccessTokenErrorCode(err),
+        }),
+      };
+    }
+
+    if (!onRequestCartesiaAccessToken) {
+      return {
+        unicast: formatCartesiaAccessTokenError({
+          voiceSessionId: payload.voiceSessionId,
+          error: "requestCartesiaAccessToken is not available",
+          code: "cartesia_access_token_unavailable",
+        }),
+      };
+    }
+
+    try {
+      const result = onRequestCartesiaAccessToken(clientId, payload);
+      if (result && typeof result.then === "function") {
+        return result.then(
+          (resolved) => ({ unicast: formatCartesiaAccessToken(resolved || payload) }),
+          (err) => ({
+            unicast: formatCartesiaAccessTokenError({
+              voiceSessionId: payload.voiceSessionId,
+              error: err && err.message ? err.message : "requestCartesiaAccessToken failed",
+              code: normalizeCartesiaAccessTokenErrorCode(err),
+            }),
+          }),
+        );
+      }
+      return { unicast: formatCartesiaAccessToken(result || payload) };
+    } catch (err) {
+      return {
+        unicast: formatCartesiaAccessTokenError({
+          voiceSessionId: payload.voiceSessionId,
+          error: err && err.message ? err.message : "requestCartesiaAccessToken failed",
+          code: normalizeCartesiaAccessTokenErrorCode(err),
+        }),
+      };
+    }
+  }
+
   function handleDebugSet(clientId, msg) {
     if (!onDebugSet) {
       return { unicast: formatError("debug-set is not available") };
@@ -3098,9 +3250,6 @@ function createDownstreamHandler(opts) {
     }
   }
 
-  /**
-   * Handle a "debug-dump" message: fetch structured debug events.
-   */
   function handleDebugDump(clientId, msg) {
     if (!onDebugDump) {
       return { unicast: formatError("debug-dump is not available") };
@@ -3157,9 +3306,6 @@ function createDownstreamHandler(opts) {
     }
   }
 
-  /**
-   * Handle a "remote-control" message: dispatch remote actions to app clients.
-   */
   function handleRemoteControl(clientId, msg) {
     if (!onRemoteControl) {
       return { unicast: formatError("remote-control is not available") };
@@ -3340,16 +3486,8 @@ function createDownstreamHandler(opts) {
     }
   }
 
-  // --- Public API ---
-
   return {
-    /**
-     * Process an incoming downstream message.
-     *
-     * @param {string} clientId - Identifier of the sending client
-     * @param {string} raw - Raw JSON string
-     * @returns {{ unicast: string }|{ broadcast: string }|null|Promise}
-     */
+
     handleMessage(clientId, raw) {
       let msg;
       try {
@@ -3372,6 +3510,10 @@ function createDownstreamHandler(opts) {
       switch (msg.type) {
         case APP_PROTOCOL.messageSend:
           return handleSend(clientId, msg);
+        case APP_PROTOCOL.sessionAbort:
+          return handleAbortSession(clientId, msg);
+        case APP_PROTOCOL.sessionSteer:
+          return handleSteerSession(clientId, msg);
         case "simulate":
           return handleSimulate(clientId, msg);
         case "simulateStream":
@@ -3384,6 +3526,8 @@ function createDownstreamHandler(opts) {
           return handleNewChat(clientId);
         case APP_PROTOCOL.sessionList:
           return handleGetSessions(clientId);
+        case APP_PROTOCOL.sessionListDiff:
+          return handleGetSessionDiff(clientId, msg);
         case APP_PROTOCOL.sessionSwitch:
           return handleSwitchSession(clientId, msg);
         case APP_PROTOCOL.sessionCreate:
@@ -3401,6 +3545,9 @@ function createDownstreamHandler(opts) {
         case APP_PROTOCOL.skillsCatalogGet:
         case "getSkills":
           return handleGetSkillsCatalog(clientId);
+        case APP_PROTOCOL.agentsCatalogGet:
+        case "getAgentsCatalog":
+          return handleGetAgentsCatalog(clientId);
         case APP_PROTOCOL.sonioxModelsGet:
         case "getSonioxModels":
           return handleGetSonioxModels(clientId);
@@ -3414,6 +3561,9 @@ function createDownstreamHandler(opts) {
           return handleGetSessionModelConfig(clientId);
         case APP_PROTOCOL.sessionConfigSet:
           return handleSetSessionModelConfig(clientId, msg);
+        case APP_PROTOCOL.sessionAgentSet:
+        case "setSessionAgent":
+          return handleSetSessionAgent(clientId, msg);
         case APP_PROTOCOL.sessionCompact:
           return handleCompactSession(clientId, msg);
         case APP_PROTOCOL.evenAiSettingsGet:
@@ -3437,10 +3587,46 @@ function createDownstreamHandler(opts) {
           return handleRemovedListenAction(msg.type);
         case APP_PROTOCOL.requestSonioxTemporaryKey:
           return handleRequestSonioxTemporaryKey(clientId, msg);
+        case APP_PROTOCOL.requestCartesiaAccessToken:
+          return handleRequestCartesiaAccessToken(clientId, msg);
         case "debug-set":
           return handleDebugSet(clientId, msg);
         case "debug-dump":
           return handleDebugDump(clientId, msg);
+        case "debug-bundle-request":
+
+          if (typeof onDebugBundleRequest === "function") {
+            try {
+              onDebugBundleRequest(clientId, msg);
+            } catch (err) {
+              logger.warn(
+                `[downstream] debug-bundle-request handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
+        case "debug-bundle-save":
+          if (typeof onDebugBundleSave === "function") {
+            try {
+              onDebugBundleSave(clientId, msg);
+            } catch (err) {
+              logger.warn(
+                `[downstream] debug-bundle-save handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
+        case "debug-bundle-fetch":
+          if (typeof onDebugBundleFetch === "function") {
+            try {
+              onDebugBundleFetch(clientId, msg);
+            } catch (err) {
+              logger.warn(
+                `[downstream] debug-bundle-fetch handler threw: ${err && err.message ? err.message : err}`,
+              );
+            }
+          }
+          return null;
         case "trace-log-set":
           return handleTraceLogSet(clientId, msg);
         case "trace-log-get":
@@ -3468,10 +3654,7 @@ function createDownstreamHandler(opts) {
           }
           return null;
         case "glasses_ui_nav_event":
-          // Client-reported nav-stack transition (push reports the PARENT
-          // surfaceId; pop reports the post-pop depth) so the plugin can
-          // pause/resume the right surface's cron. Not a debug tool — stays out
-          // of isExternalDebugToolMessageType.
+
           if (typeof onGlassesUiNavEvent === "function") {
             try {
               onGlassesUiNavEvent({
@@ -3486,8 +3669,7 @@ function createDownstreamHandler(opts) {
           }
           return null;
         case "glasses_ui_render":
-          // Debug inject path used by tools/debugctl.js glasses-ui render to
-          // exercise the simulator paint loop without spinning up an agent.
+
           if (typeof onGlassesUiRenderInject === "function") {
             try {
               onGlassesUiRenderInject({
@@ -3531,9 +3713,12 @@ function createDownstreamHandler(opts) {
     formatProtocol,
     formatStreaming,
     formatSessions,
+    formatSessionDiff,
+    sessionInfoFingerprint,
     formatSessionSwitched,
     formatModelsCatalog,
     formatSkillsCatalog,
+    formatAgentsCatalog,
     formatSonioxModels,
     formatProviderUsageSnapshot,
     formatSessionModelConfig,
@@ -3564,21 +3749,10 @@ function createDownstreamHandler(opts) {
     formatReadinessProbeAck,
     formatError,
 
-    /**
-     * Check whether a client is subscribed to protocol frame forwarding.
-     *
-     * @param {string} clientId
-     * @returns {boolean}
-     */
     isProtocolSubscriber(clientId) {
       return protocolSubscribers.has(clientId);
     },
 
-    /**
-     * Clean up state for a disconnected client.
-     *
-     * @param {string} clientId
-     */
     removeClient(clientId) {
       protocolSubscribers.delete(clientId);
     },