ocuclaw 0.1.0 → 1.3.0

package/dist/runtime/session-service.js

@@ -1,7 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { stripAllTaggedSpans } from "../domain/tagged-span-strip.js";
 
 const SESSION_FIRST_USER_CACHE_FILE = "session-first-user-cache.json";
+const SESSION_TITLE_CACHE_FILE = "session-title-cache.json";
+const SESSION_PIN_CACHE_FILE = "ocuclaw-session-pins.json";
+const PIN_CAP_PER_KIND = 20;
+
 
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
@@ -28,6 +33,30 @@ function resolveSessionFirstUserMessageCachePath(stateDir) {
   return path.join(resolvedStateDir, SESSION_FIRST_USER_CACHE_FILE);
 }
 
+function resolveSessionTitleCachePath(stateDir) {
+  const resolvedStateDir = normalizeStateDir(stateDir);
+  if (!resolvedStateDir) return null;
+  return path.join(resolvedStateDir, SESSION_TITLE_CACHE_FILE);
+}
+
+function resolveSessionPinCachePath(stateDir) {
+  const resolvedStateDir = normalizeStateDir(stateDir);
+  if (!resolvedStateDir) return null;
+  return path.join(resolvedStateDir, SESSION_PIN_CACHE_FILE);
+}
+
+function sanitizeAssistantContentBlocks(content) {
+  if (typeof content === "string") {
+    return stripAllTaggedSpans(content);
+  }
+  if (!Array.isArray(content)) return content;
+  return content.map((block) =>
+    block && block.type === "text" && typeof block.text === "string"
+      ? { ...block, text: stripAllTaggedSpans(block.text) }
+      : block,
+  );
+}
+
 export function createSessionService(opts = {}) {
   const logger = normalizeLogger(opts.logger);
   const gatewayBridge = opts.gatewayBridge;
@@ -53,6 +82,10 @@ export function createSessionService(opts = {}) {
     typeof opts.onSessionModelConfig === "function"
       ? opts.onSessionModelConfig
       : null;
+  const isPinnedFirstUserMessageKey =
+    typeof opts.isPinnedFirstUserMessageKey === "function"
+      ? opts.isPinnedFirstUserMessageKey
+      : null;
 
   /** Current session key. Generated on first use. */
   let currentSessionKey = null;
@@ -74,7 +107,9 @@ export function createSessionService(opts = {}) {
   );
 
   /** Maximum number of sessions to fetch. */
-  const sessionLimit = opts.sessionLimit || 10;
+  // Default raised to 100 so the WebUI Sessions panel can show a full
+  // scrollable history without being chopped to 10 most-recent.
+  const sessionLimit = opts.sessionLimit || 100;
   /** Whether to persist first real user message cache to disk. */
   const persistFirstUserMessages = opts.persistFirstUserMessages !== false;
   /**
@@ -92,11 +127,11 @@ export function createSessionService(opts = {}) {
     Number.isFinite(opts.sessionCacheTtlMs) && opts.sessionCacheTtlMs > 0
       ? Math.floor(opts.sessionCacheTtlMs)
       : 5000;
-  /** @type {Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string}>|null} */
+  /** @type {Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string, title: string|null, pinned: boolean, pinnedAtMs: number|null}>|null} */
   let cachedSessions = null;
   /** Epoch ms when cachedSessions was last refreshed. */
   let cachedSessionsFetchedAt = 0;
-  /** @type {Promise<Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string}>>|null} */
+  /** @type {Promise<Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string, title: string|null, pinned: boolean, pinnedAtMs: number|null}>>|null} */
   let inFlightSessionsFetch = null;
 
   /** Last-known session model config per session key. */
@@ -109,6 +144,18 @@ export function createSessionService(opts = {}) {
   /** @type {Map<string, string>} First real user text observed from downstream send events. */
   const firstSentUserMessageBySession = loadFirstSentUserMessageCache();
 
+  /** Path for session title cache file. */
+  const sessionTitleCachePath = resolveSessionTitleCachePath(opts.stateDir);
+  /** @type {Map<string, {title: string, setAtMs: number, userSet: boolean}>} Per-session agent- or user-set title. */
+  const sessionTitleByKey = loadSessionTitleCache();
+  /** @type {Map<string, boolean>} Per-session Neural Session Names toggle state. */
+  const neuralSessionNamesEnabledByKey = new Map();
+
+  /** Path for session pin metadata cache file. */
+  const sessionPinCachePath = resolveSessionPinCachePath(opts.stateDir);
+  /** @type {Map<string, {pinned: boolean, pinnedAtMs: number}>} Per-session pin metadata. */
+  const sessionPinByKey = loadSessionPinCache();
+
   /**
    * Generate a new OcuClaw session key.
    * @returns {string} e.g. "ocuclaw:1739500000000"
@@ -191,6 +238,17 @@ export function createSessionService(opts = {}) {
     return "off";
   }
 
+  // Preserves all four gateway values — "ask" is the alias of "on" and must
+  // not be collapsed, or snapshot read-back would lie about /elevated ask.
+  function normalizeElevatedLevel(raw) {
+    if (typeof raw !== "string") return "off";
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "on" || normalized === "ask" || normalized === "full") {
+      return normalized;
+    }
+    return "off";
+  }
+
   function normalizeSessionModelRef(modelProviderRaw, modelRaw) {
     let modelProvider =
       typeof modelProviderRaw === "string" && modelProviderRaw.trim()
@@ -223,6 +281,8 @@ export function createSessionService(opts = {}) {
       thinkingLevel: normalizeThinkingLevel(row && row.thinkingLevel),
       reasoningLevel: normalizeReasoningLevel(row && row.reasoningLevel),
       verboseLevel: normalizeVerboseLevel(row && row.verboseLevel),
+      fastMode: !!(row && row.fastMode === true),
+      elevatedLevel: normalizeElevatedLevel(row && row.elevatedLevel),
     };
   }
 
@@ -336,6 +396,14 @@ export function createSessionService(opts = {}) {
         patch && Object.prototype.hasOwnProperty.call(patch, "verboseLevel")
           ? normalizeVerboseLevel(patch.verboseLevel)
           : base.verboseLevel,
+      fastMode:
+        patch && Object.prototype.hasOwnProperty.call(patch, "fastMode")
+          ? patch.fastMode === true
+          : base.fastMode,
+      elevatedLevel:
+        patch && Object.prototype.hasOwnProperty.call(patch, "elevatedLevel")
+          ? normalizeElevatedLevel(patch.elevatedLevel)
+          : base.elevatedLevel,
     };
     sessionModelConfigCache.set(sessionKey, config);
     return config;
@@ -353,6 +421,13 @@ export function createSessionService(opts = {}) {
       }
       const config = buildSessionModelConfig(sessionKey, row);
       sessionModelConfigCache.set(sessionKey, config);
+      if (
+        onSessionModelConfig &&
+        normalizeSessionKeyForCompare(sessionKey) ===
+          normalizeSessionKeyForCompare(ensureSessionKey())
+      ) {
+        onSessionModelConfig(config);
+      }
       return config;
     } catch (err) {
       emitDebug(
@@ -390,7 +465,7 @@ export function createSessionService(opts = {}) {
     }
     const request = { key: canonicalKey };
     if (patch && typeof patch.modelRef === "string") {
-      request.model = patch.modelRef;
+      request.model = patch.modelRef.trim() ? patch.modelRef : null;
     }
     if (patch && Object.prototype.hasOwnProperty.call(patch, "thinkingLevel")) {
       request.thinkingLevel =
@@ -404,15 +479,24 @@ export function createSessionService(opts = {}) {
     if (patch && typeof patch.verboseLevel === "string") {
       request.verboseLevel = patch.verboseLevel;
     }
+    if (patch && typeof patch.fastMode === "boolean") {
+      request.fastMode = patch.fastMode;
+    }
+    if (patch && typeof patch.elevatedLevel === "string") {
+      request.elevatedLevel = patch.elevatedLevel;
+    }
 
     try {
       await gatewayBridge.request("sessions.patch", request);
-      const config = await getSessionModelConfig(sessionKey);
-      sessionModelConfigCache.set(sessionKey, config);
-      pendingInitialConfigSessionKeys.delete(sessionKey);
-      if (onSessionModelConfig && normalizeSessionKeyForCompare(sessionKey) === normalizeSessionKeyForCompare(ensureSessionKey())) {
+      const config = primeSessionModelConfig(sessionKey, patch);
+      if (
+        onSessionModelConfig &&
+        normalizeSessionKeyForCompare(sessionKey) ===
+          normalizeSessionKeyForCompare(ensureSessionKey())
+      ) {
         onSessionModelConfig(config);
       }
+      pendingInitialConfigSessionKeys.delete(sessionKey);
       return { status: "accepted", config };
     } catch (err) {
       emitDebug(
@@ -438,7 +522,7 @@ export function createSessionService(opts = {}) {
   /**
    * Fetch the list of OcuClaw sessions from OpenClaw.
    * Filters to OcuClaw session key prefix, sorted by updatedAt descending.
-   * @returns {Promise<Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string}>>}
+   * @returns {Promise<Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string, title: string|null, pinned: boolean, pinnedAtMs: number|null}>>}
    */
   async function getSessions() {
     if (cachedSessions && Date.now() - cachedSessionsFetchedAt < sessionCacheTtlMs) {
@@ -474,6 +558,7 @@ export function createSessionService(opts = {}) {
             updatedAt,
             row.messages,
           );
+          const pinMeta = getSessionPin(key);
           return {
             key,
             updatedAt,
@@ -483,6 +568,9 @@ export function createSessionService(opts = {}) {
                 ? ""
                 : extractPreview(row.messages),
             firstUserMessage,
+            title: resolveRowTitle(key, row),
+            pinned: pinMeta.pinned,
+            pinnedAtMs: pinMeta.pinnedAtMs,
           };
         }),
       );
@@ -505,11 +593,15 @@ export function createSessionService(opts = {}) {
             updatedAt,
             [],
           );
+          const pinMeta = getSessionPin(pendingSessionListKey);
           sessions.unshift({
             key: pendingSessionListKey,
             updatedAt,
             preview: firstUserMessage ? firstUserMessage.slice(0, 80) : "",
             firstUserMessage,
+            title: resolveRowTitle(pendingSessionListKey, null),
+            pinned: pinMeta.pinned,
+            pinnedAtMs: pinMeta.pinnedAtMs,
           });
         }
       }
@@ -574,6 +666,7 @@ export function createSessionService(opts = {}) {
         updatedAt,
         fallbackMessages,
       );
+      const pinMeta = getSessionPin(key);
       sessions.push({
         key,
         updatedAt,
@@ -583,6 +676,9 @@ export function createSessionService(opts = {}) {
             ? ""
             : extractPreview(fallbackMessages),
         firstUserMessage,
+        title: resolveRowTitle(key, row),
+        pinned: pinMeta.pinned,
+        pinnedAtMs: pinMeta.pinnedAtMs,
       });
     }
 
@@ -663,6 +759,18 @@ export function createSessionService(opts = {}) {
     return "";
   }
 
+  function resolveRowTitle(sessionKey, row) {
+    const cached = getSessionTitle(sessionKey);
+    if (cached !== null) return cached;
+    // row.displayName: upstream session-row label per
+    // openclaw/docs/reference/session-management-compaction.md §169.
+    if (row && typeof row.displayName === "string") {
+      const trimmed = row.displayName.trim();
+      if (trimmed) return trimmed;
+    }
+    return null;
+  }
+
   function extractMessageText(content) {
     if (typeof content === "string") {
       return normalizeSessionText(content);
@@ -696,13 +804,13 @@ export function createSessionService(opts = {}) {
     return text.replace(/\s+/g, " ").trim();
   }
 
-  function loadFirstSentUserMessageCache() {
-    if (!persistFirstUserMessages || !firstUserMessageCachePath) return new Map();
+  function loadSessionTitleCache() {
+    if (!sessionTitleCachePath) return new Map();
     try {
-      if (!fs.existsSync(firstUserMessageCachePath)) {
+      if (!fs.existsSync(sessionTitleCachePath)) {
         return new Map();
       }
-      const raw = fs.readFileSync(firstUserMessageCachePath, "utf8");
+      const raw = fs.readFileSync(sessionTitleCachePath, "utf8");
       const parsed = JSON.parse(raw);
       const sessions =
         parsed &&
@@ -713,31 +821,34 @@ export function createSessionService(opts = {}) {
           : {};
       const out = new Map();
       for (const [sessionKey, value] of Object.entries(sessions)) {
-        const normalized = normalizeSessionText(value);
-        if (!sessionKey || !normalized) continue;
-        out.set(sessionKey, normalized);
-      }
-      while (out.size > firstUserMessageCacheLimit) {
-        const oldestKey = out.keys().next().value;
-        if (oldestKey === undefined) break;
-        out.delete(oldestKey);
+        if (!sessionKey || !value || typeof value !== "object") continue;
+        const title = typeof value.title === "string" ? value.title : "";
+        if (!title) continue;
+        const setAtMs = Number.isFinite(value.setAtMs) ? Math.floor(value.setAtMs) : 0;
+        const userSet = value.userSet === true;
+        out.set(sessionKey, { title, setAtMs, userSet });
       }
+      pruneSessionTitleEntries(out);
       return out;
     } catch {
       return new Map();
     }
   }
 
-  function persistFirstSentUserMessageCache() {
-    if (!persistFirstUserMessages || !firstUserMessageCachePath) return;
+  function persistSessionTitleCache() {
+    if (!sessionTitleCachePath) return;
     try {
-      fs.mkdirSync(path.dirname(firstUserMessageCachePath), { recursive: true });
+      fs.mkdirSync(path.dirname(sessionTitleCachePath), { recursive: true });
       const sessions = {};
-      for (const [sessionKey, text] of firstSentUserMessageBySession) {
-        sessions[sessionKey] = text;
+      for (const [sessionKey, value] of sessionTitleByKey) {
+        sessions[sessionKey] = {
+          title: value.title,
+          setAtMs: value.setAtMs,
+          userSet: value.userSet === true,
+        };
       }
       fs.writeFileSync(
-        firstUserMessageCachePath,
+        sessionTitleCachePath,
         JSON.stringify(
           {
             version: 1,
@@ -750,17 +861,388 @@ export function createSessionService(opts = {}) {
       );
     } catch (err) {
       logger.error(
-        `[relay] Failed to persist session first-user cache: ${err.message}`,
+        `[relay] Failed to persist session title cache: ${err.message}`,
       );
     }
   }
 
-  function pruneFirstSentUserMessageCache() {
-    while (firstSentUserMessageBySession.size > firstUserMessageCacheLimit) {
-      const oldestKey = firstSentUserMessageBySession.keys().next().value;
-      if (oldestKey === undefined) break;
-      firstSentUserMessageBySession.delete(oldestKey);
+  function loadSessionPinCache() {
+    if (!sessionPinCachePath) return new Map();
+    try {
+      if (!fs.existsSync(sessionPinCachePath)) return new Map();
+      const raw = fs.readFileSync(sessionPinCachePath, "utf8");
+      const parsed = JSON.parse(raw);
+      const out = new Map();
+      for (const [key, value] of Object.entries(parsed ?? {})) {
+        if (
+          value &&
+          typeof value === "object" &&
+          typeof value.pinnedAtMs === "number"
+        ) {
+          out.set(key, { pinned: !!value.pinned, pinnedAtMs: value.pinnedAtMs });
+        }
+      }
+      return out;
+    } catch {
+      return new Map();
+    }
+  }
+
+  function persistSessionPinCache() {
+    if (!sessionPinCachePath) return;
+    try {
+      fs.mkdirSync(path.dirname(sessionPinCachePath), { recursive: true });
+      const obj = {};
+      for (const [key, value] of sessionPinByKey.entries()) {
+        obj[key] = value;
+      }
+      fs.writeFileSync(sessionPinCachePath, JSON.stringify(obj), "utf8");
+    } catch (err) {
+      logger.error(`[relay] Failed to persist session pin cache: ${err.message}`);
+    }
+  }
+
+  function countPinnedForKind(kind) {
+    let n = 0;
+    for (const [key, val] of sessionPinByKey.entries()) {
+      if (!val.pinned) continue;
+      if (kind === "ocuclaw" && key.startsWith("ocuclaw:")) n++;
+      else if (kind === "evenai" && key.startsWith("evenai:")) n++;
+    }
+    return n;
+  }
+
+  function getSessionPin(sessionKey) {
+    const v = sessionPinByKey.get(sessionKey);
+    return v ?? { pinned: false, pinnedAtMs: null };
+  }
+
+  /**
+   * Set or clear the pin on a session.
+   * @param {string} kind "ocuclaw" | "evenai"
+   * @param {string} sessionKey
+   * @param {boolean} pinned
+   * @returns {{ ok: true } | { ok: false, reason: "cap" | "invalid" }}
+   */
+  function setSessionPinned(kind, sessionKey, pinned) {
+    if (!sessionKey || (kind !== "ocuclaw" && kind !== "evenai")) {
+      return { ok: false, reason: "invalid" };
+    }
+    if (pinned) {
+      const countForKind = countPinnedForKind(kind);
+      const already = sessionPinByKey.get(sessionKey)?.pinned === true;
+      if (!already && countForKind >= PIN_CAP_PER_KIND) {
+        return { ok: false, reason: "cap" };
+      }
+      sessionPinByKey.set(sessionKey, { pinned: true, pinnedAtMs: Date.now() });
+    } else {
+      sessionPinByKey.delete(sessionKey);
+    }
+    persistSessionPinCache();
+    invalidateSessionsCache();
+    return { ok: true };
+  }
+
+  /**
+   * Delete one or more sessions, sequentially.
+   * Partial failures do not abort the batch.
+   * @param {"ocuclaw"|"evenai"} kind
+   * @param {string[]} sessionKeys
+   * @returns {Promise<{ deleted: string[], failed: Array<{ key: string, reason: string }> }>}
+   */
+  async function deleteSessions(kind, sessionKeys) {
+    const deleted = [];
+    const failed = [];
+    for (const key of sessionKeys) {
+      try {
+        await deleteSingleSession(kind, key);
+        sessionPinByKey.delete(key);
+        sessionTitleByKey.delete(key);
+        firstSentUserMessageBySession.delete(key);
+        deleted.push(key);
+      } catch (err) {
+        failed.push({ key, reason: err?.message ?? "unknown" });
+      }
+    }
+    persistSessionPinCache();
+    persistSessionTitleCache();
+    invalidateSessionsCache();
+    return { deleted, failed };
+  }
+
+  /**
+   * Deep transcript search across all OcuClaw sessions returned by getSessions().
+   * Returns at most `maxSnippets` snippets matching the query (case-insensitive),
+   * each with `before`/`match`/`after` slices so the UI can highlight the hit.
+   * @param {string} kind "ocuclaw" | "evenai"
+   * @param {string} query
+   * @returns {Promise<{snippets: Array<{sessionKey: string, role: string, updatedAtMs: number, before: string, match: string, after: string}>, truncated: boolean}>}
+   */
+  async function searchTranscripts(kind, query) {
+    const needle = (typeof query === "string" ? query.trim() : "").toLowerCase();
+    if (!needle) return { snippets: [], truncated: false };
+    const maxSnippets = 50;
+    const contextChars = 60;
+    const sessions = await getSessions().catch(() => []);
+    const snippets = [];
+    let truncated = false;
+    for (const session of sessions) {
+      if (snippets.length >= maxSnippets) {
+        truncated = true;
+        break;
+      }
+      if (kind === "ocuclaw" && !session.key.startsWith("ocuclaw:")) continue;
+      if (kind === "evenai" && !session.key.startsWith("evenai:")) continue;
+      let history;
+      try {
+        history = await gatewayBridge.request("chat.history", {
+          sessionKey: session.key,
+          limit: 200,
+        });
+      } catch {
+        continue;
+      }
+      const messages = (history && Array.isArray(history.messages)) ? history.messages : [];
+      for (const msg of messages) {
+        if (snippets.length >= maxSnippets) {
+          truncated = true;
+          break;
+        }
+        const text = extractRawMessageText(msg);
+        if (!text) continue;
+        const lower = text.toLowerCase();
+        const idx = lower.indexOf(needle);
+        if (idx < 0) continue;
+        const matchEnd = idx + needle.length;
+        const before = text.slice(Math.max(0, idx - contextChars), idx);
+        const match = text.slice(idx, matchEnd);
+        const after = text.slice(matchEnd, Math.min(text.length, matchEnd + contextChars));
+        snippets.push({
+          sessionKey: session.key,
+          role: typeof msg.role === "string" ? msg.role : "",
+          updatedAtMs: session.updatedAt || 0,
+          before,
+          match,
+          after,
+        });
+      }
+    }
+    return { snippets, truncated };
+  }
+
+  function extractRawMessageText(msg) {
+    if (!msg) return "";
+    if (typeof msg.content === "string") return msg.content;
+    if (Array.isArray(msg.content)) {
+      let acc = "";
+      for (const block of msg.content) {
+        if (block && block.type === "text" && typeof block.text === "string") {
+          acc += (acc ? "\n" : "") + block.text;
+        }
+      }
+      return acc;
+    }
+    return "";
+  }
+
+  async function deleteSingleSession(kind, key) {
+    // OpenClaw gateway exposes `sessions.delete({key, deleteTranscript, emitLifecycleHooks})`.
+    // Resolve to a canonical key first so prefixes like "agent:main:" are applied
+    // when the gateway expects them.
+    const canonicalKey = await resolveSessionCanonicalKey(key);
+    await gatewayBridge.request("sessions.delete", {
+      key: canonicalKey,
+      deleteTranscript: true,
+      emitLifecycleHooks: false,
+    });
+  }
+
+  /**
+   * Switch first if the active session is in the batch; then delete.
+   * Used when the UI sets `switchBeforeDelete=true`.
+   * @param {"ocuclaw"|"evenai"} kind
+   * @param {string[]} sessionKeys
+   */
+  async function switchAndDeleteSessions(kind, sessionKeys) {
+    if (
+      kind === "ocuclaw" &&
+      currentSessionKey &&
+      sessionKeys.includes(currentSessionKey)
+    ) {
+      await newSession();
+    }
+    return deleteSessions(kind, sessionKeys);
+  }
+
+  /**
+   * Re-fetch + broadcast the sessions snapshot for a given kind.
+   * Used by handlers after pin/delete writes.
+   * @param {"ocuclaw"|"evenai"} kind
+   */
+  async function broadcastSessionsForKind(kind) {
+    invalidateSessionsCache();
+    if (kind === "ocuclaw" && typeof opts.broadcastSessions === "function") {
+      try {
+        await opts.broadcastSessions();
+      } catch (err) {
+        logger.error(
+          `[relay] broadcastSessions failed: ${err?.message ?? err}`,
+        );
+      }
+    } else if (
+      kind === "evenai" &&
+      typeof opts.broadcastEvenAiSessions === "function"
+    ) {
+      try {
+        await opts.broadcastEvenAiSessions();
+      } catch (err) {
+        logger.error(
+          `[relay] broadcastEvenAiSessions failed: ${err?.message ?? err}`,
+        );
+      }
+    }
+  }
+
+  function pruneSessionTitleEntries(cache) {
+    while (cache.size > firstUserMessageCacheLimit) {
+      let evicted = false;
+      for (const sessionKey of cache.keys()) {
+        if (shouldPinFirstUserMessageKey(sessionKey)) {
+          continue;
+        }
+        cache.delete(sessionKey);
+        evicted = true;
+        break;
+      }
+      if (!evicted) {
+        break;
+      }
+    }
+  }
+
+  function loadFirstSentUserMessageCache() {
+    if (!persistFirstUserMessages || !firstUserMessageCachePath) return new Map();
+    try {
+      if (!fs.existsSync(firstUserMessageCachePath)) {
+        return new Map();
+      }
+      const raw = fs.readFileSync(firstUserMessageCachePath, "utf8");
+      const parsed = JSON.parse(raw);
+      const sessions =
+        parsed &&
+        parsed.version === 1 &&
+        parsed.sessions &&
+        typeof parsed.sessions === "object"
+          ? parsed.sessions
+          : {};
+      const out = new Map();
+      for (const [sessionKey, value] of Object.entries(sessions)) {
+        const normalized = normalizeSessionText(value);
+        if (!sessionKey || !normalized) continue;
+        out.set(sessionKey, normalized);
+      }
+      pruneFirstUserMessageEntries(out);
+      return out;
+    } catch {
+      return new Map();
+    }
+  }
+
+  // Coalesced async persistence for the first-user-message cache. Mirrors the
+  // ocuclaw-settings-store writeInFlight/pendingWrite shape (commit 6285bc24)
+  // so the SYNC fs.mkdirSync + fs.writeFileSync no longer block the hot send
+  // path on every first user message per session.
+  //
+  // The write serializes the WHOLE in-memory map, so it is a full-snapshot
+  // replace (not a disk read-modify-write). Concurrent fire-and-forget writes
+  // could therefore lose updates (an older snapshot landing after a newer one).
+  // We coalesce: at most one write in flight; any schedule while a write is in
+  // flight marks the cache dirty, and the in-flight write re-runs once it
+  // settles — so the final on-disk file always reflects the latest map.
+  let firstUserCacheWriteInFlight = false;
+  let firstUserCacheDirty = false;
+  let firstUserCacheFlushPromise = null;
+  let firstUserCacheFlushResolve = null;
+
+  async function writeFirstSentUserMessageCacheToDisk() {
+    const sessions = {};
+    for (const [sessionKey, text] of firstSentUserMessageBySession) {
+      sessions[sessionKey] = text;
+    }
+    const payload =
+      JSON.stringify(
+        {
+          version: 1,
+          updatedAtMs: Date.now(),
+          sessions,
+        },
+        null,
+        2,
+      ) + "\n";
+    const tmpPath = `${firstUserMessageCachePath}.tmp`;
+    try {
+      await fs.promises.mkdir(path.dirname(firstUserMessageCachePath), {
+        recursive: true,
+      });
+      await fs.promises.writeFile(tmpPath, payload);
+      await fs.promises.rename(tmpPath, firstUserMessageCachePath);
+    } catch (err) {
+      logger.error(
+        `[relay] Failed to persist session first-user cache: ${err && err.message ? err.message : err}`,
+      );
+    }
+  }
+
+  function runFirstSentUserMessageCacheWrite() {
+    if (firstUserCacheWriteInFlight) {
+      return;
+    }
+    if (!firstUserCacheDirty) {
+      // Nothing more to write — settle any awaiters and clear the flush gate.
+      if (firstUserCacheFlushResolve) {
+        const resolve = firstUserCacheFlushResolve;
+        firstUserCacheFlushResolve = null;
+        firstUserCacheFlushPromise = null;
+        resolve();
+      }
+      return;
     }
+    firstUserCacheDirty = false;
+    firstUserCacheWriteInFlight = true;
+    writeFirstSentUserMessageCacheToDisk().finally(() => {
+      firstUserCacheWriteInFlight = false;
+      // Re-run drains any dirty mark accumulated during this write, then
+      // settles the flush gate once the map and disk agree.
+      runFirstSentUserMessageCacheWrite();
+    });
+  }
+
+  function persistFirstSentUserMessageCache() {
+    if (!persistFirstUserMessages || !firstUserMessageCachePath) return;
+    firstUserCacheDirty = true;
+    runFirstSentUserMessageCacheWrite();
+  }
+
+  // Awaitable flush: resolves once no write is in flight AND no dirty mark is
+  // pending (the on-disk file reflects the latest in-memory map). Used by tests
+  // after rapid sends and available for graceful shutdown.
+  function flushFirstSentUserMessageCache() {
+    if (!persistFirstUserMessages || !firstUserMessageCachePath) {
+      return Promise.resolve();
+    }
+    if (!firstUserCacheWriteInFlight && !firstUserCacheDirty) {
+      return Promise.resolve();
+    }
+    if (!firstUserCacheFlushPromise) {
+      firstUserCacheFlushPromise = new Promise((resolve) => {
+        firstUserCacheFlushResolve = resolve;
+      });
+    }
+    return firstUserCacheFlushPromise;
+  }
+
+  function pruneFirstSentUserMessageCache() {
+    pruneFirstUserMessageEntries(firstSentUserMessageBySession);
   }
 
   function recordFirstSentUserMessage(sessionKey, text) {
@@ -779,6 +1261,91 @@ export function createSessionService(opts = {}) {
     pruneFirstUserMessageCache();
   }
 
+  function getSessionTitle(sessionKey) {
+    const entry = sessionTitleByKey.get(sessionKey);
+    return entry ? entry.title : null;
+  }
+
+  function setSessionTitle(sessionKey, title, opts) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) {
+      return { ok: false, code: "invalid_session_key" };
+    }
+    if (typeof title !== "string" || !title.trim()) {
+      return { ok: false, code: "invalid_title" };
+    }
+    const trimmed = title.trim();
+    const setByUser = !!(opts && opts.userSet === true);
+    const previous = sessionTitleByKey.get(sessionKey);
+
+    if (!setByUser && previous && previous.userSet === true) {
+      return { ok: false, code: "session_user_locked" };
+    }
+
+    const replaced = !!previous;
+    const nextUserSet = setByUser || (previous && previous.userSet === true);
+    sessionTitleByKey.set(sessionKey, {
+      title: trimmed,
+      setAtMs: Date.now(),
+      userSet: !!nextUserSet,
+    });
+    pruneSessionTitleEntries(sessionTitleByKey);
+    persistSessionTitleCache();
+    invalidateSessionsCache();
+    emitDebug(
+      "relay.session",
+      setByUser ? "session_title_set_by_user" : "session_title_set",
+      "info",
+      { sessionKey },
+      () => ({ sessionKey, title: trimmed, replaced, userSet: !!nextUserSet }),
+    );
+    // Fire-and-forget upstream mirror.
+    if (isUpstreamConnected()) {
+      resolveSessionCanonicalKey(sessionKey)
+        .then((canonicalKey) =>
+          gatewayBridge.request("sessions.patch", {
+            key: canonicalKey,
+            displayName: trimmed,
+          }),
+        )
+        .catch((err) => {
+          emitDebug(
+            "relay.session",
+            "session_title_upstream_patch_failed",
+            "debug",
+            { sessionKey },
+            () => ({ message: err && err.message ? err.message : String(err) }),
+          );
+        });
+    }
+    return { ok: true, replaced, userSet: !!nextUserSet };
+  }
+
+  function isSessionUserLocked(sessionKey) {
+    const entry = sessionTitleByKey.get(sessionKey);
+    return entry ? entry.userSet === true : false;
+  }
+
+  function hasRecordedFirstUserMessage(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return false;
+    return firstSentUserMessageBySession.has(sessionKey);
+  }
+
+  function recordNeuralSessionNamesEnabled(sessionKey, enabled) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return;
+    neuralSessionNamesEnabledByKey.set(sessionKey, enabled === true);
+    while (neuralSessionNamesEnabledByKey.size > firstUserMessageCacheLimit) {
+      const oldest = neuralSessionNamesEnabledByKey.keys().next().value;
+      if (oldest === undefined) break;
+      neuralSessionNamesEnabledByKey.delete(oldest);
+    }
+  }
+
+  function isNeuralSessionNamesEnabled(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) return true;
+    const cached = neuralSessionNamesEnabledByKey.get(sessionKey);
+    return cached === undefined ? true : cached;
+  }
+
   function isSyntheticSessionStarter(text) {
     if (!text) return false;
     if (
@@ -810,10 +1377,41 @@ export function createSessionService(opts = {}) {
   }
 
   function pruneFirstUserMessageCache() {
-    while (firstUserMessageCache.size > firstUserMessageCacheLimit) {
-      const oldestKey = firstUserMessageCache.keys().next().value;
-      if (oldestKey === undefined) break;
-      firstUserMessageCache.delete(oldestKey);
+    pruneFirstUserMessageEntries(firstUserMessageCache);
+  }
+
+  function shouldPinFirstUserMessageKey(sessionKey) {
+    if (!isPinnedFirstUserMessageKey || typeof sessionKey !== "string") {
+      return false;
+    }
+    const normalizedKey = sessionKey.trim();
+    if (!normalizedKey) {
+      return false;
+    }
+    try {
+      return isPinnedFirstUserMessageKey(normalizedKey) === true;
+    } catch (err) {
+      logger.warn(
+        `[relay] first-user cache pin callback failed for ${normalizedKey}: ${err && err.message ? err.message : err}`,
+      );
+      return false;
+    }
+  }
+
+  function pruneFirstUserMessageEntries(cache) {
+    while (cache.size > firstUserMessageCacheLimit) {
+      let evicted = false;
+      for (const sessionKey of cache.keys()) {
+        if (shouldPinFirstUserMessageKey(sessionKey)) {
+          continue;
+        }
+        cache.delete(sessionKey);
+        evicted = true;
+        break;
+      }
+      if (!evicted) {
+        break;
+      }
     }
   }
 
@@ -918,7 +1516,14 @@ export function createSessionService(opts = {}) {
         });
         const messages =
           result && Array.isArray(result.messages) ? result.messages : [];
-        conversationState.hydrate(messages, getAgentName());
+        const sanitized = Array.isArray(messages)
+          ? messages.map((msg) =>
+              msg && msg.role === "assistant"
+                ? { ...msg, content: sanitizeAssistantContentBlocks(msg.content) }
+                : msg,
+            )
+          : messages;
+        conversationState.hydrate(sanitized, getAgentName());
       } catch (err) {
         logger.error(
           `[relay] Failed to load session history: ${err.message}`,
@@ -1008,6 +1613,7 @@ export function createSessionService(opts = {}) {
     peekSessionKey,
     createDetachedSessionKey,
     recordFirstSentUserMessage,
+    flushFirstSentUserMessageCache,
     invalidateSessionsCache,
     handleUpstreamStatusChange,
     getSessionModelConfig,
@@ -1018,9 +1624,21 @@ export function createSessionService(opts = {}) {
     hasPendingInitialConfig,
     clearPendingInitialConfig,
     getSessions,
+    getSessionTitle,
     getSessionsByExactKeys,
+    hasRecordedFirstUserMessage,
+    isNeuralSessionNamesEnabled,
+    isSessionUserLocked,
+    recordNeuralSessionNamesEnabled,
+    setSessionTitle,
     switchToSession,
     newSession,
     isCurrentSession,
+    setSessionPinned,
+    getSessionPin,
+    deleteSessions,
+    switchAndDeleteSessions,
+    broadcastSessionsForKind,
+    searchTranscripts,
   };
 }