ocuclaw 1.2.4 → 1.3.1

package/dist/runtime/session-service.js

@@ -1,7 +1,30 @@
 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;
+
+/**
+ * Greeting-eliciting content appended to /new and /reset so OpenClaw runs an
+ * agent turn (the new-session "welcome"). OpenClaw 2026.6.x ("make bare reset
+ * commands fast", gateway commit 2c6a3f6b04) made a BARE /new or /reset return
+ * a synchronous ack and run NO agent turn — so a bare reset no longer produces
+ * a welcome and leaves the glasses stuck on the "starting new session"
+ * placeholder. Sending "/new <prompt>" / "/reset <prompt>" routes through the
+ * gateway's normal agent path (content = the prompt) and elicits the welcome.
+ * The wording matches the prompt OpenClaw used to inject itself, so the
+ * existing synthetic-session-starter filters (conversation-state display hide +
+ * isSyntheticSessionStarter title/preview filter) keep it hidden from the
+ * transcript and session titles. NOTE: newSession() does NOT call
+ * conversationState.addMessage("user", ...), so this content never renders as a
+ * user bubble on the glasses.
+ */
+export const NEW_SESSION_GREETING_PROMPT =
+  "A new session was started via /new or /reset. Execute your Session Startup sequence now - read the required files before responding to the user. If BOOTSTRAP.md exists in the provided Project Context, read it and follow its instructions first. Then greet the user in your configured persona, if one is provided. Be yourself - use your defined voice, mannerisms, and mood. Keep it to 1-3 sentences and ask what they want to do. If the runtime model differs from default_model in the system prompt, mention the default model. Do not mention internal steps, files, tools, or reasoning.";
+
 
 function normalizeLogger(logger) {
   if (!logger || typeof logger !== "object") {
@@ -28,6 +51,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;
@@ -78,7 +125,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;
   /**
@@ -96,11 +145,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. */
@@ -113,6 +162,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"
@@ -195,6 +256,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()
@@ -227,6 +299,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),
     };
   }
 
@@ -340,6 +414,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;
@@ -357,6 +439,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(
@@ -408,15 +497,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(
@@ -442,7 +540,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) {
@@ -478,6 +576,7 @@ export function createSessionService(opts = {}) {
             updatedAt,
             row.messages,
           );
+          const pinMeta = getSessionPin(key);
           return {
             key,
             updatedAt,
@@ -487,6 +586,9 @@ export function createSessionService(opts = {}) {
                 ? ""
                 : extractPreview(row.messages),
             firstUserMessage,
+            title: resolveRowTitle(key, row),
+            pinned: pinMeta.pinned,
+            pinnedAtMs: pinMeta.pinnedAtMs,
           };
         }),
       );
@@ -509,11 +611,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,
           });
         }
       }
@@ -578,6 +684,7 @@ export function createSessionService(opts = {}) {
         updatedAt,
         fallbackMessages,
       );
+      const pinMeta = getSessionPin(key);
       sessions.push({
         key,
         updatedAt,
@@ -587,6 +694,9 @@ export function createSessionService(opts = {}) {
             ? ""
             : extractPreview(fallbackMessages),
         firstUserMessage,
+        title: resolveRowTitle(key, row),
+        pinned: pinMeta.pinned,
+        pinnedAtMs: pinMeta.pinnedAtMs,
       });
     }
 
@@ -667,6 +777,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);
@@ -700,13 +822,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 &&
@@ -717,27 +839,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);
+        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 });
       }
-      pruneFirstUserMessageEntries(out);
+      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,11 +879,386 @@ 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 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);
   }
@@ -775,6 +1279,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 (
@@ -945,7 +1534,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}`,
@@ -997,9 +1593,11 @@ export function createSessionService(opts = {}) {
       onStatusChanged();
     }
     if (sendResetCommand && isUpstreamConnected()) {
-      gatewayBridge.sendMessage("/new", sessionKey).catch((err) => {
-        logger.error(`[relay] Failed to send /new for new session: ${err.message}`);
-      });
+      gatewayBridge
+        .sendMessage(`/new ${NEW_SESSION_GREETING_PROMPT}`, sessionKey)
+        .catch((err) => {
+          logger.error(`[relay] Failed to send /new for new session: ${err.message}`);
+        });
     }
     return { sessionKey, pages };
   }
@@ -1035,6 +1633,7 @@ export function createSessionService(opts = {}) {
     peekSessionKey,
     createDetachedSessionKey,
     recordFirstSentUserMessage,
+    flushFirstSentUserMessageCache,
     invalidateSessionsCache,
     handleUpstreamStatusChange,
     getSessionModelConfig,
@@ -1045,9 +1644,21 @@ export function createSessionService(opts = {}) {
     hasPendingInitialConfig,
     clearPendingInitialConfig,
     getSessions,
+    getSessionTitle,
     getSessionsByExactKeys,
+    hasRecordedFirstUserMessage,
+    isNeuralSessionNamesEnabled,
+    isSessionUserLocked,
+    recordNeuralSessionNamesEnabled,
+    setSessionTitle,
     switchToSession,
     newSession,
     isCurrentSession,
+    setSessionPinned,
+    getSessionPin,
+    deleteSessions,
+    switchAndDeleteSessions,
+    broadcastSessionsForKind,
+    searchTranscripts,
   };
 }