ocuclaw 0.1.0

package/dist/runtime/session-service.js

@@ -0,0 +1,1026 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SESSION_FIRST_USER_CACHE_FILE = "session-first-user-cache.json";
+
+function normalizeLogger(logger) {
+  if (!logger || typeof logger !== "object") {
+    return console;
+  }
+  return {
+    info: typeof logger.info === "function" ? logger.info.bind(logger) : console.log,
+    warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn,
+    error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error,
+    debug:
+      typeof logger.debug === "function" ? logger.debug.bind(logger) : console.debug,
+  };
+}
+
+function normalizeStateDir(stateDir) {
+  if (typeof stateDir !== "string") return null;
+  const trimmed = stateDir.trim();
+  return trimmed ? trimmed : null;
+}
+
+function resolveSessionFirstUserMessageCachePath(stateDir) {
+  const resolvedStateDir = normalizeStateDir(stateDir);
+  if (!resolvedStateDir) return null;
+  return path.join(resolvedStateDir, SESSION_FIRST_USER_CACHE_FILE);
+}
+
+export function createSessionService(opts = {}) {
+  const logger = normalizeLogger(opts.logger);
+  const gatewayBridge = opts.gatewayBridge;
+  const conversationState = opts.conversationState;
+  const emitDebug = typeof opts.emitDebug === "function" ? opts.emitDebug : () => {};
+  const getAgentName =
+    typeof opts.getAgentName === "function" ? opts.getAgentName : () => null;
+  const isUpstreamConnected =
+    typeof opts.isUpstreamConnected === "function"
+      ? opts.isUpstreamConnected
+      : typeof opts.getOpenclawConnected === "function"
+        ? opts.getOpenclawConnected
+      : () => false;
+  const onSessionStateReset =
+    typeof opts.onSessionStateReset === "function"
+      ? opts.onSessionStateReset
+      : null;
+  const onPagesChanged =
+    typeof opts.onPagesChanged === "function" ? opts.onPagesChanged : null;
+  const onStatusChanged =
+    typeof opts.onStatusChanged === "function" ? opts.onStatusChanged : null;
+  const onSessionModelConfig =
+    typeof opts.onSessionModelConfig === "function"
+      ? opts.onSessionModelConfig
+      : null;
+
+  /** Current session key. Generated on first use. */
+  let currentSessionKey = null;
+  /** Locally-created session key pending visibility in upstream sessions.list. */
+  let pendingSessionListKey = null;
+  let lastGeneratedSessionTimestamp = 0;
+  const DEFAULT_SESSION_KEY_PREFIX =
+    typeof opts.defaultSessionKeyPrefix === "string" &&
+    opts.defaultSessionKeyPrefix.trim()
+      ? opts.defaultSessionKeyPrefix.trim()
+      : "ocuclaw:";
+  const SUPPORTED_SESSION_KEY_PREFIXES =
+    Array.isArray(opts.supportedSessionKeyPrefixes) &&
+    opts.supportedSessionKeyPrefixes.length > 0
+      ? opts.supportedSessionKeyPrefixes
+      : [DEFAULT_SESSION_KEY_PREFIX];
+  const SUPPORTED_SESSION_KEY_PREFIXES_LOWER = SUPPORTED_SESSION_KEY_PREFIXES.map(
+    (prefix) => String(prefix || "").toLowerCase(),
+  );
+
+  /** Maximum number of sessions to fetch. */
+  const sessionLimit = opts.sessionLimit || 10;
+  /** Whether to persist first real user message cache to disk. */
+  const persistFirstUserMessages = opts.persistFirstUserMessages !== false;
+  /**
+   * Strict mode by default: only use first real downstream sends for session preview labels.
+   * Set to false to re-enable legacy chat.history/fallback extraction.
+   */
+  const strictFirstUserMessage = opts.strictFirstUserMessage !== false;
+  /** Path for first real user message cache file. */
+  const firstUserMessageCachePath = resolveSessionFirstUserMessageCachePath(
+    opts.stateDir,
+  );
+
+  /** TTL for cached sessions.list payloads. */
+  const sessionCacheTtlMs =
+    Number.isFinite(opts.sessionCacheTtlMs) && opts.sessionCacheTtlMs > 0
+      ? Math.floor(opts.sessionCacheTtlMs)
+      : 5000;
+  /** @type {Array<{key: string, updatedAt: number, preview: string, firstUserMessage: string}>|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} */
+  let inFlightSessionsFetch = null;
+
+  /** Last-known session model config per session key. */
+  const sessionModelConfigCache = new Map();
+  /** New OcuClaw sessions awaiting one-time default model/thinking seeding. */
+  const pendingInitialConfigSessionKeys = new Set();
+  /** @type {Map<string, {updatedAt: number, firstUserMessage: string}>} */
+  const firstUserMessageCache = new Map();
+  const firstUserMessageCacheLimit = Math.max(64, sessionLimit * 8);
+  /** @type {Map<string, string>} First real user text observed from downstream send events. */
+  const firstSentUserMessageBySession = loadFirstSentUserMessageCache();
+
+  /**
+   * Generate a new OcuClaw session key.
+   * @returns {string} e.g. "ocuclaw:1739500000000"
+   */
+  function generateSessionKey(rawPrefix = DEFAULT_SESSION_KEY_PREFIX) {
+    const effectivePrefix =
+      typeof rawPrefix === "string" && rawPrefix.trim()
+        ? rawPrefix.trim()
+        : DEFAULT_SESSION_KEY_PREFIX;
+    const nowMs = Date.now();
+    const nextTimestamp =
+      nowMs > lastGeneratedSessionTimestamp
+        ? nowMs
+        : lastGeneratedSessionTimestamp + 1;
+    lastGeneratedSessionTimestamp = nextTimestamp;
+    return `${effectivePrefix}${nextTimestamp}`;
+  }
+
+  /**
+   * Get or create the current session key.
+   * @returns {string}
+   */
+  function ensureSessionKey() {
+    if (!currentSessionKey) {
+      currentSessionKey = generateSessionKey();
+    }
+    return currentSessionKey;
+  }
+
+  function peekSessionKey() {
+    return currentSessionKey;
+  }
+
+  function createDetachedSessionKey(prefix) {
+    const sessionKey = generateSessionKey(prefix);
+    invalidateSessionsCache();
+    pendingSessionListKey = sessionKey;
+    emitDebug(
+      "relay.session",
+      "detached_session_prepared",
+      "info",
+      { sessionKey },
+      () => ({
+        sessionKey,
+      }),
+    );
+    return sessionKey;
+  }
+
+  function normalizeThinkingLevel(raw) {
+    if (typeof raw !== "string") return "";
+    const normalized = raw.trim().toLowerCase();
+    if (
+      normalized === "off" ||
+      normalized === "minimal" ||
+      normalized === "low" ||
+      normalized === "medium" ||
+      normalized === "high" ||
+      normalized === "xhigh"
+    ) {
+      return normalized;
+    }
+    return "";
+  }
+
+  function normalizeReasoningLevel(raw) {
+    if (typeof raw !== "string") return "off";
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "stream") return "stream";
+    if (normalized === "on") return "on";
+    return "off";
+  }
+
+  function normalizeVerboseLevel(raw) {
+    if (typeof raw !== "string") return "off";
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "off" || normalized === "on" || normalized === "full") {
+      return normalized;
+    }
+    return "off";
+  }
+
+  function normalizeSessionModelRef(modelProviderRaw, modelRaw) {
+    let modelProvider =
+      typeof modelProviderRaw === "string" && modelProviderRaw.trim()
+        ? modelProviderRaw.trim()
+        : null;
+    let model =
+      typeof modelRaw === "string" && modelRaw.trim() ? modelRaw.trim() : null;
+    if (model && model.includes("/")) {
+      const slashIdx = model.indexOf("/");
+      const splitProvider = model.slice(0, slashIdx).trim();
+      const splitModel = model.slice(slashIdx + 1).trim();
+      if (!modelProvider && splitProvider) modelProvider = splitProvider;
+      model = splitModel || model;
+    }
+    return {
+      modelProvider,
+      model,
+    };
+  }
+
+  function buildSessionModelConfig(sessionKey, row) {
+    const normalized = normalizeSessionModelRef(
+      row && row.modelProvider,
+      row && row.model,
+    );
+    return {
+      sessionKey,
+      modelProvider: normalized.modelProvider,
+      model: normalized.model,
+      thinkingLevel: normalizeThinkingLevel(row && row.thinkingLevel),
+      reasoningLevel: normalizeReasoningLevel(row && row.reasoningLevel),
+      verboseLevel: normalizeVerboseLevel(row && row.verboseLevel),
+    };
+  }
+
+  function listSessionsBySearch(search) {
+    return gatewayBridge.request("sessions.list", {
+      search,
+      includeGlobal: false,
+      includeUnknown: false,
+      limit: 10,
+    });
+  }
+
+  async function resolveSessionCanonicalKey(sessionKey) {
+    if (!isUpstreamConnected()) return sessionKey;
+    if (hasSupportedSessionKeyPrefix(sessionKey)) {
+      return sessionKey;
+    }
+    try {
+      const resolved = await gatewayBridge.request("sessions.resolve", {
+        key: sessionKey,
+        includeGlobal: false,
+        includeUnknown: false,
+      });
+      if (resolved && typeof resolved.key === "string" && resolved.key.trim()) {
+        return resolved.key.trim();
+      }
+    } catch {
+      // keep raw key fallback
+    }
+    return sessionKey;
+  }
+
+  function normalizeExactSessionKey(rawKey) {
+    if (typeof rawKey !== "string") return "";
+    const trimmed = rawKey.trim();
+    if (!trimmed) return "";
+    const shortKey = extractShortKey(trimmed);
+    return hasSupportedSessionKeyPrefix(shortKey) ? shortKey : "";
+  }
+
+  function findBestSessionRow(rows, targetKey, canonicalKey) {
+    if (!Array.isArray(rows) || rows.length === 0) return null;
+    const targetShort = extractShortKey(targetKey || "");
+    const canonicalShort = extractShortKey(canonicalKey || "");
+
+    const fullCanonicalMatch = rows.find((row) => {
+      return row && typeof row.key === "string" && canonicalKey && row.key === canonicalKey;
+    });
+    if (fullCanonicalMatch) return fullCanonicalMatch;
+
+    const shortCanonicalMatch = rows.find((row) => {
+      if (!row || typeof row.key !== "string") return false;
+      return canonicalShort && extractShortKey(row.key) === canonicalShort;
+    });
+    if (shortCanonicalMatch) return shortCanonicalMatch;
+
+    return (
+      rows.find((row) => {
+        if (!row || typeof row.key !== "string") return false;
+        return targetShort && extractShortKey(row.key) === targetShort;
+      }) || null
+    );
+  }
+
+  async function fetchCurrentSessionRow(sessionKey) {
+    const canonicalKey = await resolveSessionCanonicalKey(sessionKey);
+    const firstResult = await listSessionsBySearch(sessionKey);
+    const firstRows =
+      firstResult && Array.isArray(firstResult.sessions)
+        ? firstResult.sessions
+        : [];
+    const firstMatch = findBestSessionRow(firstRows, sessionKey, canonicalKey);
+    if (firstMatch) {
+      return { row: firstMatch, canonicalKey };
+    }
+
+    const secondResult = await listSessionsBySearch(canonicalKey);
+    const secondRows =
+      secondResult && Array.isArray(secondResult.sessions)
+        ? secondResult.sessions
+        : [];
+    const secondMatch = findBestSessionRow(secondRows, sessionKey, canonicalKey);
+    return { row: secondMatch, canonicalKey };
+  }
+
+  function cachedSessionModelConfig(sessionKey) {
+    return sessionModelConfigCache.get(sessionKey) || buildSessionModelConfig(sessionKey, null);
+  }
+
+  function primeSessionModelConfig(sessionKey, patch) {
+    const base = cachedSessionModelConfig(sessionKey);
+    const normalizedModel = Object.prototype.hasOwnProperty.call(patch || {}, "modelRef")
+      ? normalizeSessionModelRef(null, patch && patch.modelRef)
+      : {
+          modelProvider: base.modelProvider,
+          model: base.model,
+        };
+    const config = {
+      sessionKey,
+      modelProvider: normalizedModel.modelProvider,
+      model: normalizedModel.model,
+      thinkingLevel:
+        patch && Object.prototype.hasOwnProperty.call(patch, "thinkingLevel")
+          ? normalizeThinkingLevel(patch.thinkingLevel)
+          : base.thinkingLevel,
+      reasoningLevel:
+        patch && Object.prototype.hasOwnProperty.call(patch, "reasoningEnabled")
+          ? normalizeReasoningLevel(patch.reasoningEnabled ? "on" : "off")
+          : base.reasoningLevel,
+      verboseLevel:
+        patch && Object.prototype.hasOwnProperty.call(patch, "verboseLevel")
+          ? normalizeVerboseLevel(patch.verboseLevel)
+          : base.verboseLevel,
+    };
+    sessionModelConfigCache.set(sessionKey, config);
+    return config;
+  }
+
+  async function getSessionModelConfig(sessionKey = ensureSessionKey()) {
+    if (!isUpstreamConnected()) {
+      return cachedSessionModelConfig(sessionKey);
+    }
+    try {
+      const resolved = await fetchCurrentSessionRow(sessionKey);
+      const row = resolved && resolved.row ? resolved.row : null;
+      if (!row) {
+        return cachedSessionModelConfig(sessionKey);
+      }
+      const config = buildSessionModelConfig(sessionKey, row);
+      sessionModelConfigCache.set(sessionKey, config);
+      return config;
+    } catch (err) {
+      emitDebug(
+        "relay.session",
+        "session_model_config_fetch_failed",
+        "warn",
+        { sessionKey },
+        () => ({
+          message: err && err.message ? err.message : String(err),
+        }),
+      );
+      return cachedSessionModelConfig(sessionKey);
+    }
+  }
+
+  async function getCurrentSessionModelConfig() {
+    return getSessionModelConfig(ensureSessionKey());
+  }
+
+  async function setSessionModelConfig(sessionKey = ensureSessionKey(), patch) {
+    if (!isUpstreamConnected()) {
+      return {
+        status: "rejected",
+        error: "OpenClaw disconnected",
+      };
+    }
+
+    let canonicalKey = await resolveSessionCanonicalKey(sessionKey);
+    if (hasSupportedSessionKeyPrefix(sessionKey)) {
+      const resolved = await fetchCurrentSessionRow(sessionKey);
+      const row = resolved && resolved.row ? resolved.row : null;
+      if (row && typeof row.key === "string" && row.key.trim()) {
+        canonicalKey = row.key.trim();
+      }
+    }
+    const request = { key: canonicalKey };
+    if (patch && typeof patch.modelRef === "string") {
+      request.model = patch.modelRef;
+    }
+    if (patch && Object.prototype.hasOwnProperty.call(patch, "thinkingLevel")) {
+      request.thinkingLevel =
+        typeof patch.thinkingLevel === "string" && patch.thinkingLevel.trim()
+          ? normalizeThinkingLevel(patch.thinkingLevel)
+          : null;
+    }
+    if (patch && patch.reasoningEnabled !== undefined) {
+      request.reasoningLevel = patch.reasoningEnabled ? "on" : "off";
+    }
+    if (patch && typeof patch.verboseLevel === "string") {
+      request.verboseLevel = patch.verboseLevel;
+    }
+
+    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())) {
+        onSessionModelConfig(config);
+      }
+      return { status: "accepted", config };
+    } catch (err) {
+      emitDebug(
+        "relay.session",
+        "session_model_config_set_failed",
+        "warn",
+        { sessionKey },
+        () => ({
+          message: err && err.message ? err.message : String(err),
+        }),
+      );
+      return {
+        status: "rejected",
+        error: err && err.message ? err.message : "sessions.patch failed",
+      };
+    }
+  }
+
+  async function setCurrentSessionModelConfig(patch) {
+    return setSessionModelConfig(ensureSessionKey(), patch);
+  }
+
+  /**
+   * 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}>>}
+   */
+  async function getSessions() {
+    if (cachedSessions && Date.now() - cachedSessionsFetchedAt < sessionCacheTtlMs) {
+      return cachedSessions;
+    }
+    if (inFlightSessionsFetch) {
+      return inFlightSessionsFetch;
+    }
+    if (!isUpstreamConnected()) {
+      return cachedSessions || [];
+    }
+
+    inFlightSessionsFetch = (async () => {
+      const result = await gatewayBridge.request("sessions.list", {
+        limit: sessionLimit,
+      });
+      const rows = (result && result.sessions) || [];
+      const sortedRows = rows
+        .filter((row) => {
+          const key = extractShortKey(row && row.key);
+          return hasSupportedSessionKeyPrefix(key) && !isEvenAiSessionKey(key);
+        })
+        .sort((left, right) => (right.updatedAt || 0) - (left.updatedAt || 0));
+
+      const sessions = await Promise.all(
+        sortedRows.map(async (row) => {
+          const key = extractShortKey(row.key);
+          const updatedAt = Number.isFinite(row.updatedAt)
+            ? Math.floor(row.updatedAt)
+            : 0;
+          const firstUserMessage = await resolveFirstUserMessage(
+            key,
+            updatedAt,
+            row.messages,
+          );
+          return {
+            key,
+            updatedAt,
+            preview: firstUserMessage
+              ? firstUserMessage.slice(0, 80)
+              : strictFirstUserMessage
+                ? ""
+                : extractPreview(row.messages),
+            firstUserMessage,
+          };
+        }),
+      );
+
+      if (
+        typeof pendingSessionListKey === "string" &&
+        hasSupportedSessionKeyPrefix(pendingSessionListKey) &&
+        !isEvenAiSessionKey(pendingSessionListKey)
+      ) {
+        const hasPendingSession = sessions.some((session) =>
+          sameSessionKey(session && session.key, pendingSessionListKey),
+        );
+        if (hasPendingSession) {
+          pendingSessionListKey = null;
+        } else {
+          const updatedAt =
+            extractSessionTimestampFromKey(pendingSessionListKey) || Date.now();
+          const firstUserMessage = await resolveFirstUserMessage(
+            pendingSessionListKey,
+            updatedAt,
+            [],
+          );
+          sessions.unshift({
+            key: pendingSessionListKey,
+            updatedAt,
+            preview: firstUserMessage ? firstUserMessage.slice(0, 80) : "",
+            firstUserMessage,
+          });
+        }
+      }
+
+      return cacheSessions(sessions);
+    })();
+
+    return inFlightSessionsFetch.finally(() => {
+      inFlightSessionsFetch = null;
+    });
+  }
+
+  async function getSessionsByExactKeys(sessionKeys) {
+    if (!Array.isArray(sessionKeys) || sessionKeys.length === 0) {
+      return [];
+    }
+    if (!isUpstreamConnected()) {
+      return [];
+    }
+
+    const orderedKeys = [];
+    const seen = new Set();
+    for (const rawKey of sessionKeys) {
+      const normalizedKey = normalizeExactSessionKey(rawKey);
+      if (!normalizedKey) continue;
+      const dedupeKey = normalizedKey.toLowerCase();
+      if (seen.has(dedupeKey)) continue;
+      seen.add(dedupeKey);
+      orderedKeys.push(normalizedKey);
+    }
+
+    const sessions = [];
+    for (const sessionKey of orderedKeys) {
+      let resolved;
+      try {
+        resolved = await fetchCurrentSessionRow(sessionKey);
+      } catch (err) {
+        emitDebug(
+          "relay.session",
+          "session_exact_lookup_failed",
+          "debug",
+          { sessionKey },
+          () => ({
+            message: err && err.message ? err.message : String(err),
+          }),
+        );
+        continue;
+      }
+
+      const row = resolved && resolved.row ? resolved.row : null;
+      if (!row) {
+        continue;
+      }
+
+      const key = extractShortKey(row.key || sessionKey);
+      const updatedAt = Number.isFinite(row.updatedAt)
+        ? Math.floor(row.updatedAt)
+        : 0;
+      const fallbackMessages = Array.isArray(row.messages) ? row.messages : [];
+      const firstUserMessage = await resolveFirstUserMessage(
+        key,
+        updatedAt,
+        fallbackMessages,
+      );
+      sessions.push({
+        key,
+        updatedAt,
+        preview: firstUserMessage
+          ? firstUserMessage.slice(0, 80)
+          : strictFirstUserMessage
+            ? ""
+            : extractPreview(fallbackMessages),
+        firstUserMessage,
+      });
+    }
+
+    return sessions;
+  }
+
+  /**
+   * Extract the short session key from a fully-qualified gateway key.
+   * "agent:main:ocuclaw:1234567890" -> "ocuclaw:1234567890"
+   * @param {string} fullKey
+   * @returns {string}
+   */
+  function extractShortKey(fullKey) {
+    if (typeof fullKey !== "string") return "";
+    const fullKeyLower = fullKey.toLowerCase();
+    let prefixIndex = -1;
+    for (const prefix of SUPPORTED_SESSION_KEY_PREFIXES_LOWER) {
+      const idx = fullKeyLower.indexOf(prefix);
+      if (idx >= 0 && (prefixIndex < 0 || idx < prefixIndex)) {
+        prefixIndex = idx;
+      }
+    }
+    return prefixIndex >= 0 ? fullKey.slice(prefixIndex) : fullKey;
+  }
+
+  /**
+   * Check whether a full/canonical session key belongs to a supported
+   * OcuClaw session namespace.
+   * @param {string} key
+   * @returns {boolean}
+   */
+  function hasSupportedSessionKeyPrefix(key) {
+    if (typeof key !== "string" || key.length === 0) return false;
+    const keyLower = key.toLowerCase();
+    return SUPPORTED_SESSION_KEY_PREFIXES_LOWER.some((prefix) => keyLower.includes(prefix));
+  }
+
+  function isEvenAiSessionKey(key) {
+    if (typeof key !== "string" || !key.trim()) return false;
+    const normalized = extractShortKey(key).toLowerCase();
+    return (
+      normalized === "ocuclaw:even-ai" ||
+      normalized.startsWith("ocuclaw:even-ai:")
+    );
+  }
+
+  function sameSessionKey(left, right) {
+    if (typeof left !== "string" || typeof right !== "string") return false;
+    return left.toLowerCase() === right.toLowerCase();
+  }
+
+  /**
+   * Best-effort timestamp extraction from session key suffix.
+   * "ocuclaw:1739500000000" -> 1739500000000
+   * @param {string} sessionKey
+   * @returns {number}
+   */
+  function extractSessionTimestampFromKey(sessionKey) {
+    if (typeof sessionKey !== "string") return 0;
+    const idx = sessionKey.lastIndexOf(":");
+    if (idx < 0 || idx >= sessionKey.length - 1) return 0;
+    const maybeTs = Number.parseInt(sessionKey.slice(idx + 1), 10);
+    return Number.isFinite(maybeTs) && maybeTs > 0 ? maybeTs : 0;
+  }
+
+  /**
+   * Extract a preview string from a session's messages array.
+   * @param {Array} messages - Last N messages from sessions.list
+   * @returns {string}
+   */
+  function extractPreview(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) return "";
+    for (const msg of messages) {
+      const text = extractMessageText(msg && msg.content);
+      if (!text || isSyntheticSessionStarter(text)) continue;
+      return text.slice(0, 80);
+    }
+    return "";
+  }
+
+  function extractMessageText(content) {
+    if (typeof content === "string") {
+      return normalizeSessionText(content);
+    }
+    if (!Array.isArray(content)) return "";
+    const textParts = [];
+    for (const block of content) {
+      if (block && block.type === "text" && typeof block.text === "string") {
+        const text = normalizeSessionText(block.text);
+        if (text) textParts.push(text);
+      }
+    }
+    return normalizeSessionText(textParts.join(" "));
+  }
+
+  function extractFirstUserMessage(messages) {
+    if (!Array.isArray(messages) || messages.length === 0) return "";
+    for (const msg of messages) {
+      const role =
+        msg && typeof msg.role === "string" ? msg.role.toLowerCase() : "";
+      if (role !== "user") continue;
+      const text = extractMessageText(msg.content);
+      if (isSyntheticSessionStarter(text)) continue;
+      if (text) return text;
+    }
+    return "";
+  }
+
+  function normalizeSessionText(text) {
+    if (typeof text !== "string") return "";
+    return text.replace(/\s+/g, " ").trim();
+  }
+
+  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);
+      }
+      while (out.size > firstUserMessageCacheLimit) {
+        const oldestKey = out.keys().next().value;
+        if (oldestKey === undefined) break;
+        out.delete(oldestKey);
+      }
+      return out;
+    } catch {
+      return new Map();
+    }
+  }
+
+  function persistFirstSentUserMessageCache() {
+    if (!persistFirstUserMessages || !firstUserMessageCachePath) return;
+    try {
+      fs.mkdirSync(path.dirname(firstUserMessageCachePath), { recursive: true });
+      const sessions = {};
+      for (const [sessionKey, text] of firstSentUserMessageBySession) {
+        sessions[sessionKey] = text;
+      }
+      fs.writeFileSync(
+        firstUserMessageCachePath,
+        JSON.stringify(
+          {
+            version: 1,
+            updatedAtMs: Date.now(),
+            sessions,
+          },
+          null,
+          2,
+        ) + "\n",
+      );
+    } catch (err) {
+      logger.error(
+        `[relay] Failed to persist session first-user cache: ${err.message}`,
+      );
+    }
+  }
+
+  function pruneFirstSentUserMessageCache() {
+    while (firstSentUserMessageBySession.size > firstUserMessageCacheLimit) {
+      const oldestKey = firstSentUserMessageBySession.keys().next().value;
+      if (oldestKey === undefined) break;
+      firstSentUserMessageBySession.delete(oldestKey);
+    }
+  }
+
+  function recordFirstSentUserMessage(sessionKey, text) {
+    const normalized = normalizeSessionText(text);
+    if (!normalized || normalized.startsWith("/")) return;
+    if (firstSentUserMessageBySession.has(sessionKey)) return;
+
+    firstSentUserMessageBySession.set(sessionKey, normalized);
+    pruneFirstSentUserMessageCache();
+    persistFirstSentUserMessageCache();
+
+    firstUserMessageCache.set(sessionKey, {
+      updatedAt: Number.MAX_SAFE_INTEGER,
+      firstUserMessage: normalized,
+    });
+    pruneFirstUserMessageCache();
+  }
+
+  function isSyntheticSessionStarter(text) {
+    if (!text) return false;
+    if (
+      typeof conversationState._isLikelySyntheticSessionStarterPrompt === "function" &&
+      conversationState._isLikelySyntheticSessionStarterPrompt(text)
+    ) {
+      return true;
+    }
+    const normalized = normalizeSessionText(text).toLowerCase();
+    if (!normalized.includes("/new") || !normalized.includes("/reset")) return false;
+    if (/^a\s+new\s+session\s+was\s+started\b/.test(normalized)) return true;
+    if (normalized.length < 80) return false;
+    if (
+      !/\b(?:new|fresh)\s+session\b|\bsession\b.*\b(?:started|reset|created)\b/.test(normalized)
+    ) {
+      return false;
+    }
+
+    let signalCount = 0;
+    if (/\bgreet\b/.test(normalized)) signalCount += 1;
+    if (/\bconfigured\b.*\b(?:persona|style|voice)\b/.test(normalized)) signalCount += 1;
+    if (/\bbe yourself\b|\bmannerisms\b|\bmood\b/.test(normalized)) signalCount += 1;
+    if (/\b(?:1-3|1 to 3|one to three)\s+sentences?\b/.test(normalized)) signalCount += 1;
+    if (/\bask\b.*\bwhat\b.*\bwant\b.*\bdo\b/.test(normalized)) signalCount += 1;
+    if (/\bdefault(?:_| )model\b/.test(normalized)) signalCount += 1;
+    if (/\bdo not mention\b/.test(normalized)) signalCount += 1;
+    if (/\binternal\b.*\b(?:steps|files|tools|reasoning)\b/.test(normalized)) signalCount += 1;
+    return signalCount >= 2;
+  }
+
+  function pruneFirstUserMessageCache() {
+    while (firstUserMessageCache.size > firstUserMessageCacheLimit) {
+      const oldestKey = firstUserMessageCache.keys().next().value;
+      if (oldestKey === undefined) break;
+      firstUserMessageCache.delete(oldestKey);
+    }
+  }
+
+  async function resolveFirstUserMessage(sessionKey, updatedAt, fallbackMessages) {
+    const firstObservedUserMessage = firstSentUserMessageBySession.get(sessionKey);
+    if (firstObservedUserMessage) {
+      return firstObservedUserMessage;
+    }
+
+    const cached = firstUserMessageCache.get(sessionKey);
+    if (cached && cached.firstUserMessage) {
+      return cached.firstUserMessage;
+    }
+    if (cached && cached.updatedAt === updatedAt) {
+      return cached.firstUserMessage;
+    }
+
+    if (strictFirstUserMessage) {
+      firstUserMessageCache.set(sessionKey, { updatedAt, firstUserMessage: "" });
+      pruneFirstUserMessageCache();
+      return "";
+    }
+
+    let firstUserMessage = "";
+    if (isUpstreamConnected()) {
+      try {
+        const result = await gatewayBridge.request("chat.history", {
+          sessionKey,
+          limit: 200,
+        });
+        firstUserMessage = extractFirstUserMessage(
+          result && Array.isArray(result.messages) ? result.messages : [],
+        );
+      } catch (err) {
+        emitDebug(
+          "relay.session",
+          "session_first_message_lookup_failed",
+          "debug",
+          { sessionKey },
+          () => ({
+            message: err && err.message ? err.message : String(err),
+          }),
+        );
+      }
+    }
+    if (!firstUserMessage) {
+      firstUserMessage = extractFirstUserMessage(fallbackMessages);
+    }
+    firstUserMessageCache.set(sessionKey, { updatedAt, firstUserMessage });
+    pruneFirstUserMessageCache();
+    return firstUserMessage;
+  }
+
+  function cacheSessions(sessions) {
+    cachedSessions = Array.isArray(sessions) ? sessions : [];
+    cachedSessionsFetchedAt = Date.now();
+    return cachedSessions;
+  }
+
+  function invalidateSessionsCache() {
+    cachedSessionsFetchedAt = 0;
+  }
+
+  function handleUpstreamStatusChange(connected) {
+    if (!connected) {
+      inFlightSessionsFetch = null;
+    }
+  }
+
+  /**
+   * Switch to a different session: load its history and return pages.
+   * @param {string} sessionKey
+   * @returns {Promise<Array>} Pages array
+   */
+  async function switchToSession(sessionKey, opts = {}) {
+    const markPendingSessionList =
+      opts.markPendingSessionList === true &&
+      hasSupportedSessionKeyPrefix(sessionKey);
+    invalidateSessionsCache();
+    if (onSessionStateReset) {
+      onSessionStateReset();
+    }
+    pendingSessionListKey = markPendingSessionList ? sessionKey : null;
+    currentSessionKey = sessionKey;
+    emitDebug(
+      "relay.session",
+      "switch_session",
+      "info",
+      { sessionKey },
+      () => ({
+        sessionKey,
+        markPendingSessionList,
+      }),
+    );
+    conversationState.clear();
+
+    if (isUpstreamConnected()) {
+      try {
+        const result = await gatewayBridge.request("chat.history", {
+          sessionKey,
+          limit: 200,
+        });
+        const messages =
+          result && Array.isArray(result.messages) ? result.messages : [];
+        conversationState.hydrate(messages, getAgentName());
+      } catch (err) {
+        logger.error(
+          `[relay] Failed to load session history: ${err.message}`,
+        );
+      }
+    }
+
+    const pages = conversationState.getPages();
+    if (onPagesChanged) {
+      onPagesChanged(pages);
+    }
+    if (onStatusChanged) {
+      onStatusChanged();
+    }
+    return pages;
+  }
+
+  /**
+   * Create a new session with a fresh key.
+   * @returns {Promise<{sessionKey: string, pages: Array}>}
+   */
+  async function newSession(opts = {}) {
+    const sendResetCommand = opts.sendResetCommand !== false;
+    const sessionKey = generateSessionKey();
+    invalidateSessionsCache();
+    if (onSessionStateReset) {
+      onSessionStateReset();
+    }
+    currentSessionKey = sessionKey;
+    pendingSessionListKey = sessionKey;
+    pendingInitialConfigSessionKeys.add(sessionKey);
+    emitDebug(
+      "relay.session",
+      "new_session",
+      "info",
+      { sessionKey },
+      () => ({
+        sessionKey,
+        sendResetCommand,
+      }),
+    );
+    conversationState.clear();
+    conversationState.setAgentName(getAgentName() || "Agent");
+    const pages = conversationState.getPages();
+    if (onPagesChanged) {
+      onPagesChanged(pages);
+    }
+    if (onStatusChanged) {
+      onStatusChanged();
+    }
+    if (sendResetCommand && isUpstreamConnected()) {
+      gatewayBridge.sendMessage("/new", sessionKey).catch((err) => {
+        logger.error(`[relay] Failed to send /new for new session: ${err.message}`);
+      });
+    }
+    return { sessionKey, pages };
+  }
+
+  function normalizeSessionKeyForCompare(rawKey) {
+    if (typeof rawKey !== "string") return "";
+    const trimmed = rawKey.trim();
+    if (!trimmed) return "";
+    return extractShortKey(trimmed).toLowerCase();
+  }
+
+  /**
+   * Check if an event's session key matches the current glasses session.
+   * Events without a sessionKey default to "main".
+   */
+  function isCurrentSession(eventSessionKey) {
+    const eventKey = normalizeSessionKeyForCompare(eventSessionKey || "main");
+    const currentKey = normalizeSessionKeyForCompare(ensureSessionKey());
+    if (!eventKey || !currentKey) return false;
+    return eventKey === currentKey || eventKey.endsWith(`:${currentKey}`);
+  }
+
+  function hasPendingInitialConfig(sessionKey) {
+    return pendingInitialConfigSessionKeys.has(sessionKey);
+  }
+
+  function clearPendingInitialConfig(sessionKey) {
+    pendingInitialConfigSessionKeys.delete(sessionKey);
+  }
+
+  return {
+    ensureSessionKey,
+    peekSessionKey,
+    createDetachedSessionKey,
+    recordFirstSentUserMessage,
+    invalidateSessionsCache,
+    handleUpstreamStatusChange,
+    getSessionModelConfig,
+    getCurrentSessionModelConfig,
+    setSessionModelConfig,
+    setCurrentSessionModelConfig,
+    primeSessionModelConfig,
+    hasPendingInitialConfig,
+    clearPendingInitialConfig,
+    getSessions,
+    getSessionsByExactKeys,
+    switchToSession,
+    newSession,
+    isCurrentSession,
+  };
+}