letagents 0.12.34 → 0.12.36

package/shared/message-search-controller.d.mts

@@ -0,0 +1,38 @@
+import type { MessageSearchQueryError, MessageSearchResponse } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS: 250;
+
+export interface MessageSearchState<Hit extends { id: string }> {
+  /**
+   * `idle`: nothing to search yet. `invalid`: the query breaks a limit (see `error`).
+   * `loading`: the first page is on its way. `ready` / `error`: it arrived, or failed.
+   */
+  status: "idle" | "invalid" | "loading" | "ready" | "error";
+  terms: readonly string[];
+  /** Newest first. */
+  hits: readonly Hit[];
+  hasMore: boolean;
+  loadingMore: boolean;
+  /** A query limit name when `invalid`; otherwise the last request's failure, if any. */
+  error: MessageSearchQueryError | string | null;
+}
+
+export interface MessageSearchController<Hit extends { id: string }> {
+  readonly state: MessageSearchState<Hit>;
+  /** Search for a new query after a short pause in typing. */
+  setQuery(value: string): void;
+  /** Read the next, older page of the current results. */
+  loadMore(): Promise<void>;
+  /** Stop searching; call when the search closes or the room changes. */
+  reset(): void;
+}
+
+/**
+ * The client-side state of one room's history search, shared by the desktop
+ * and web apps. Answers that arrive for an earlier query are dropped.
+ */
+export function createMessageSearchController<Hit extends { id: string }>(options: {
+  search(query: string, before: string | null): Promise<Pick<MessageSearchResponse<Hit>, "messages" | "has_more" | "next_before"> & { terms?: string[] }>;
+  onChange?(): void;
+  debounceMs?: number;
+}): MessageSearchController<Hit>;

package/shared/message-search-controller.mjs

@@ -0,0 +1,99 @@
+// The client-side state of one room's history search, shared by the desktop
+// and web apps. Framework-free: the app supplies the request and is told when
+// something changed.
+import { parseMessageSearchQuery } from "./message-search.mjs";
+
+export const MESSAGE_SEARCH_DEBOUNCE_MS = 250;
+
+const IDLE = Object.freeze({ status: "idle", terms: [], hits: [], hasMore: false, loadingMore: false, error: null });
+
+export function createMessageSearchController({ search, onChange, debounceMs = MESSAGE_SEARCH_DEBOUNCE_MS }) {
+  let state = IDLE;
+  let query = "";
+  let nextBefore = null;
+  // Every new query (and reset) starts an epoch; answers from an earlier one are dropped.
+  let epoch = 0;
+  let timer = null;
+
+  function set(next) {
+    state = next;
+    onChange?.();
+  }
+
+  function cancelTimer() {
+    if (timer !== null) clearTimeout(timer);
+    timer = null;
+  }
+
+  async function run(terms, startedIn) {
+    try {
+      const page = await search(query, null);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      set({
+        status: "ready",
+        terms: Array.isArray(page?.terms) ? page.terms : terms,
+        hits: Array.isArray(page?.messages) ? page.messages : [],
+        hasMore: Boolean(page?.has_more && nextBefore),
+        loadingMore: false,
+        error: null,
+      });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      set({ ...IDLE, status: "error", terms, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Search for a new query after a short pause in typing. */
+  function setQuery(value) {
+    const next = typeof value === "string" ? value : "";
+    if (next.trim() === query.trim() && state !== IDLE) return;
+    query = next;
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    const parsed = parseMessageSearchQuery(query);
+    if (parsed.error) {
+      // Too short is simply "not searching yet"; the other limits are worth saying.
+      set(parsed.error === "too_short" ? IDLE : { ...IDLE, status: "invalid", error: parsed.error });
+      return;
+    }
+    const startedIn = epoch;
+    set({ ...IDLE, status: "loading", terms: parsed.terms });
+    timer = setTimeout(() => {
+      timer = null;
+      void run(parsed.terms, startedIn);
+    }, debounceMs);
+  }
+
+  /** Read the next, older page of the current results. */
+  async function loadMore() {
+    if (state.status !== "ready" || !state.hasMore || state.loadingMore || !nextBefore) return;
+    const startedIn = epoch;
+    const before = nextBefore;
+    set({ ...state, loadingMore: true, error: null });
+    try {
+      const page = await search(query, before);
+      if (startedIn !== epoch) return;
+      nextBefore = page?.next_before ?? null;
+      const known = new Set(state.hits.map((hit) => hit.id));
+      const more = (Array.isArray(page?.messages) ? page.messages : []).filter((hit) => !known.has(hit.id));
+      set({ ...state, hits: [...state.hits, ...more], hasMore: Boolean(page?.has_more && nextBefore), loadingMore: false });
+    } catch (error) {
+      if (startedIn !== epoch) return;
+      // Keep what is shown; the person can press "more" again.
+      set({ ...state, loadingMore: false, error: error instanceof Error && error.message ? error.message : "Search failed." });
+    }
+  }
+
+  /** Stop searching; call when the search closes or the room changes. */
+  function reset() {
+    query = "";
+    epoch += 1;
+    cancelTimer();
+    nextBefore = null;
+    if (state !== IDLE) set(IDLE);
+  }
+
+  return { get state() { return state; }, setQuery, loadMore, reset };
+}

package/shared/message-search.d.mts

@@ -0,0 +1,46 @@
+export const MESSAGE_SEARCH_MIN_QUERY_CHARS: 2;
+export const MESSAGE_SEARCH_MAX_QUERY_CHARS: 200;
+export const MESSAGE_SEARCH_MAX_TERMS: 6;
+export const MESSAGE_SEARCH_DEFAULT_LIMIT: 30;
+export const MESSAGE_SEARCH_MAX_LIMIT: 50;
+
+export type MessageSearchQueryError = "too_short" | "too_long" | "too_many_terms";
+
+export type ParsedMessageSearchQuery =
+  | { terms: string[]; error?: undefined }
+  | { error: MessageSearchQueryError; terms?: undefined };
+
+/**
+ * Split a query into its terms, or say why it cannot be searched. A term is a
+ * word, or a phrase in double quotes; a message matches when it contains every
+ * term as a substring, ignoring case.
+ */
+export function parseMessageSearchQuery(value: unknown): ParsedMessageSearchQuery;
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text: unknown, terms: readonly string[]): boolean;
+
+/** `GET /rooms/:room/messages/search` */
+export interface MessageSearchResponse<Message = unknown> {
+  room_id: string;
+  terms: string[];
+  /** Newest first. */
+  messages: Message[];
+  has_more: boolean;
+  /** Pass as `before` to read the next, older page; null on the last page. */
+  next_before: string | null;
+}
+
+export interface MessageSearchSegment {
+  text: string;
+  match: boolean;
+}
+
+/**
+ * Split a text into runs that do and do not match the terms, for rendering
+ * highlights as plain text nodes (never as HTML).
+ */
+export function highlightMessageSearchText(text: unknown, terms: readonly string[]): MessageSearchSegment[];
+
+/** A short excerpt around the first match, with an ellipsis where text was left out. */
+export function messageSearchSnippet(text: unknown, terms: readonly string[], maxLength?: number): string;

package/shared/message-search.mjs

@@ -0,0 +1,114 @@
+// Searching a room's messages: the limits and the one query grammar that the
+// server and both apps share. A query is a list of terms; a message matches
+// when it contains every term, ignoring case. A term is a word, or a phrase
+// in double quotes. Matching is by substring, so part of an identifier, a
+// file path or an error string finds the message.
+
+export const MESSAGE_SEARCH_MIN_QUERY_CHARS = 2;
+export const MESSAGE_SEARCH_MAX_QUERY_CHARS = 200;
+export const MESSAGE_SEARCH_MAX_TERMS = 6;
+export const MESSAGE_SEARCH_DEFAULT_LIMIT = 30;
+export const MESSAGE_SEARCH_MAX_LIMIT = 50;
+
+/**
+ * Split a query into its terms, or say why it cannot be searched.
+ * Returns `{ terms }` or `{ error: "too_short" | "too_long" | "too_many_terms" }`.
+ */
+export function parseMessageSearchQuery(value) {
+  const query = typeof value === "string" ? value.trim() : "";
+  if (query.length > MESSAGE_SEARCH_MAX_QUERY_CHARS) return { error: "too_long" };
+
+  const terms = [];
+  const seen = new Set();
+  // A phrase runs to its closing quote, or to the end when the quote is never closed.
+  for (const match of query.matchAll(/"([^"]*)"?|(\S+)/g)) {
+    const term = (match[1] ?? match[2] ?? "").replace(/\s+/g, " ").trim();
+    const key = term.toLowerCase();
+    if (!term || seen.has(key)) continue;
+    seen.add(key);
+    terms.push(term);
+  }
+  if (terms.join("").length < MESSAGE_SEARCH_MIN_QUERY_CHARS) return { error: "too_short" };
+  if (terms.length > MESSAGE_SEARCH_MAX_TERMS) return { error: "too_many_terms" };
+  return { terms };
+}
+
+/** Whether a text contains every term, the same test the server applies. */
+export function textMatchesMessageSearch(text, terms) {
+  const haystack = String(text ?? "").toLowerCase();
+  return terms.length > 0 && terms.every((term) => haystack.includes(term.toLowerCase()));
+}
+
+function matchRanges(text, terms) {
+  const lower = text.toLowerCase();
+  // Lowercasing can expand a character (İ -> i + combining dot). Keep the
+  // original UTF-16 boundaries so highlights and snippets still slice source text.
+  let sourceOffsets = null;
+  if (lower.length !== text.length) {
+    sourceOffsets = [];
+    let start = 0;
+    for (const character of text) {
+      const end = start + character.length;
+      for (let index = 0; index < character.toLowerCase().length; index += 1) {
+        sourceOffsets.push([start, end]);
+      }
+      start = end;
+    }
+    // Context-sensitive casing must not leave offsets outside the map.
+    if (sourceOffsets.length !== lower.length) return [];
+  }
+  const ranges = [];
+  for (const term of terms) {
+    const needle = term.toLowerCase();
+    if (!needle) continue;
+    for (let at = lower.indexOf(needle); at !== -1; at = lower.indexOf(needle, at + 1)) {
+      ranges.push(sourceOffsets
+        ? [sourceOffsets[at][0], sourceOffsets[at + needle.length - 1][1]]
+        : [at, at + needle.length]);
+    }
+  }
+  ranges.sort((left, right) => left[0] - right[0] || left[1] - right[1]);
+  // Overlapping and touching matches read as one highlighted run.
+  const merged = [];
+  for (const range of ranges) {
+    const last = merged.at(-1);
+    if (last && range[0] <= last[1]) last[1] = Math.max(last[1], range[1]);
+    else merged.push([...range]);
+  }
+  return merged;
+}
+
+/**
+ * Split a text into runs that do and do not match the terms, for rendering
+ * highlights as plain text nodes (never as HTML).
+ */
+export function highlightMessageSearchText(text, terms) {
+  const source = String(text ?? "");
+  const segments = [];
+  let cursor = 0;
+  for (const [start, end] of matchRanges(source, terms)) {
+    if (start > cursor) segments.push({ text: source.slice(cursor, start), match: false });
+    segments.push({ text: source.slice(start, end), match: true });
+    cursor = end;
+  }
+  if (cursor < source.length) segments.push({ text: source.slice(cursor), match: false });
+  return segments;
+}
+
+/**
+ * A short excerpt around the first match: whitespace collapsed, cut at
+ * `maxLength` characters, with an ellipsis where text was left out.
+ */
+export function messageSearchSnippet(text, terms, maxLength = 220) {
+  const source = String(text ?? "").replace(/\s+/g, " ").trim();
+  if (source.length <= maxLength) return source;
+  const first = matchRanges(source, terms)[0]?.[0] ?? 0;
+  // Keep a little lead-in so the match is read in its sentence.
+  let start = Math.max(0, Math.min(first - Math.floor(maxLength / 4), source.length - maxLength));
+  if (start > 0) {
+    const space = source.indexOf(" ", start);
+    if (space !== -1 && space < first) start = space + 1;
+  }
+  const end = Math.min(source.length, start + maxLength);
+  return `${start > 0 ? "…" : ""}${source.slice(start, end).trim()}${end < source.length ? "…" : ""}`;
+}

package/shared/room-message-urls.d.mts

@@ -0,0 +1,25 @@
+export const LETAGENTS_ROOM_ORIGIN: string;
+export const MESSAGE_ID_PATTERN: RegExp;
+
+export function isValidMessageId(messageId: unknown): messageId is string;
+export function encodeRoomPathIdentifier(identifier: string): string;
+export function decodeRoomPath(path: string): string;
+export function isLocalRoomIdentifier(identifier: string | null | undefined): boolean;
+
+export function buildLetAgentsMessageUrl(
+  roomIdentifier: string,
+  messageId: string,
+  origin?: string,
+): string;
+
+export function parseLetAgentsMessageUrl(
+  rawUrl: string,
+  configuredOrigin?: string,
+): { roomIdentifier: string; messageId: string | null } | null;
+
+export function resolveSameRoomMessageReference(
+  rawUrl: string | null | undefined,
+  currentRoomIdentifier: string | null | undefined,
+  configuredOrigin?: string,
+): string | null;
+

package/shared/room-message-urls.mjs

@@ -0,0 +1,119 @@
+export const LETAGENTS_ROOM_ORIGIN = "https://letagents.chat";
+
+export const MESSAGE_ID_PATTERN = /^msg_[1-9]\d*$/;
+
+export function isValidMessageId(messageId) {
+  return typeof messageId === "string" && MESSAGE_ID_PATTERN.test(messageId);
+}
+
+export function encodeRoomPathIdentifier(identifier) {
+  return String(identifier ?? "")
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+export function decodeRoomPath(path) {
+  return String(path ?? "")
+    .split("/")
+    .map((segment) => {
+      try {
+        return decodeURIComponent(segment);
+      } catch {
+        return segment;
+      }
+    })
+    .join("/");
+}
+
+export function isLocalRoomIdentifier(identifier) {
+  const value = String(identifier ?? "").trim();
+  return /^local[_-]/i.test(value) || /^git-room:local:/i.test(value);
+}
+
+export function buildLetAgentsMessageUrl(
+  roomIdentifier,
+  messageId,
+  origin = LETAGENTS_ROOM_ORIGIN,
+) {
+  const cleanId = String(messageId ?? "").trim();
+  if (!isValidMessageId(cleanId)) {
+    throw new Error(`Invalid message ID for permalink: ${messageId}`);
+  }
+  const cleanRoom = String(roomIdentifier ?? "").trim();
+  if (!cleanRoom) {
+    throw new Error("Room identifier is required for permalink.");
+  }
+  const base = origin ? origin.replace(/\/+$/, "") : "";
+  return `${base}/in/${encodeRoomPathIdentifier(cleanRoom)}?message=${cleanId}`;
+}
+
+export function parseLetAgentsMessageUrl(
+  rawUrl,
+  configuredOrigin = LETAGENTS_ROOM_ORIGIN,
+) {
+  if (typeof rawUrl !== "string") return null;
+  const trimmed = rawUrl.trim();
+  if (!trimmed) return null;
+
+  let parsed;
+  let isRelative = false;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    if (trimmed.startsWith("/in/") || trimmed.startsWith("in/")) {
+      try {
+        parsed = new URL(trimmed.startsWith("/") ? trimmed : `/${trimmed}`, "http://localhost");
+        isRelative = true;
+      } catch {
+        return null;
+      }
+    } else {
+      return null;
+    }
+  }
+
+  if (!isRelative) {
+    let normalizedConfiguredOrigin;
+    try {
+      normalizedConfiguredOrigin = new URL(configuredOrigin).origin.toLowerCase();
+    } catch {
+      normalizedConfiguredOrigin = String(configuredOrigin).replace(/\/+$/, "").toLowerCase();
+    }
+    if (parsed.origin.toLowerCase() !== normalizedConfiguredOrigin) {
+      return null;
+    }
+  }
+
+  const pathname = parsed.pathname.replace(/^\/+|\/+$/g, "");
+  if (!pathname.startsWith("in/")) {
+    return null;
+  }
+  const rawRoom = pathname.slice("in/".length);
+  if (!rawRoom) return null;
+  const roomIdentifier = decodeRoomPath(rawRoom);
+  if (!roomIdentifier.trim()) return null;
+
+  const rawMessageId = parsed.searchParams.get("message");
+  const messageId = isValidMessageId(rawMessageId) ? rawMessageId.trim() : null;
+
+  return {
+    roomIdentifier,
+    messageId,
+  };
+}
+
+export function resolveSameRoomMessageReference(
+  rawUrl,
+  currentRoomIdentifier,
+  configuredOrigin = LETAGENTS_ROOM_ORIGIN,
+) {
+  if (typeof rawUrl !== "string" || !currentRoomIdentifier) return null;
+  const parsed = parseLetAgentsMessageUrl(rawUrl, configuredOrigin);
+  if (!parsed?.messageId) return null;
+  if (parsed.roomIdentifier.trim() !== String(currentRoomIdentifier).trim()) {
+    return null;
+  }
+  return parsed.messageId;
+}
+

package/shared/room-notification-client.d.mts

@@ -0,0 +1,18 @@
+import type { RoomNotificationPreference, RoomNotificationPreferenceChange, RoomNotificationPreferenceEntry, RoomNotificationPreferenceList } from './room-notification-preferences.mjs';
+export interface RoomNotificationClientState {
+  preference: RoomNotificationPreference; ready: boolean; loading: boolean; busy: boolean; error: string; version: number;
+}
+export declare function createRoomNotificationClient(api: {
+  get(roomId: string): Promise<RoomNotificationPreferenceEntry>;
+  list?(): Promise<RoomNotificationPreferenceList>;
+  put?(roomId: string, change: RoomNotificationPreferenceChange): Promise<RoomNotificationPreferenceEntry>;
+}, changed?: () => void, normalizeKey?: (roomId: string) => string): {
+  setViewer(viewer: { id: string; login: string } | null): void;
+  signedIn(): boolean;
+  allowsAfterRead(roomId: string, text: unknown): Promise<boolean>;
+  state(roomId: string): RoomNotificationClientState;
+  refresh(roomId: string): Promise<void>;
+  refreshAll(): Promise<void>;
+  update(roomId: string, change: RoomNotificationPreferenceChange): Promise<void>;
+  allows(roomId: string, text: unknown, now?: number): boolean;
+};

package/shared/room-notification-client.mjs

@@ -0,0 +1,140 @@
+import { allowsRoomNotification, DEFAULT_ROOM_NOTIFICATION_PREFERENCE } from './room-notification-preferences.mjs';
+
+/** Personal cache shared by desktop and the read-only web sound gate. */
+export function createRoomNotificationClient(api, changed = () => {}, normalizeKey = (id) => id) {
+  let viewer = null;
+  let epoch = 0;
+  let listVersion = 0;
+  let listLoading = false;
+  const rooms = new Map();
+  const pendingReads = new Map();
+  let pendingList = null;
+  function state(roomId) {
+    roomId = normalizeKey(roomId);
+    if (!rooms.has(roomId)) rooms.set(roomId, {
+      preference: { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE }, ready: false, loading: false,
+      busy: false, error: '', version: 0,
+    });
+    return rooms.get(roomId);
+  }
+  function setViewer(next) {
+    if (viewer?.id === next?.id && viewer?.login === next?.login) return;
+    viewer = next;
+    epoch++;
+    listVersion++;
+    listLoading = false;
+    rooms.clear();
+    pendingReads.clear();
+    pendingList = null;
+    changed();
+  }
+  async function performRefresh(roomId) {
+    if (!viewer || !roomId) return;
+    const row = state(roomId);
+    if (row.busy) return;
+    const version = ++row.version;
+    const currentEpoch = epoch;
+    row.loading = true;
+    changed();
+    try {
+      const preference = await api.get(roomId);
+      if (epoch !== currentEpoch || row.version !== version) return;
+      row.preference = preference;
+      row.error = '';
+    } catch (error) {
+      if (epoch !== currentEpoch || row.version !== version) return;
+      if (!row.ready) row.preference = { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+      row.error = error instanceof Error ? error.message : 'Notification settings could not be loaded.';
+    } finally {
+      if (epoch === currentEpoch && row.version === version) {
+        row.loading = false;
+        row.ready = true;
+        changed();
+      }
+    }
+  }
+  function refresh(roomId) {
+    roomId = normalizeKey(roomId);
+    const pending = performRefresh(roomId);
+    pendingReads.set(roomId, pending);
+    void pending.then(() => { if (pendingReads.get(roomId) === pending) pendingReads.delete(roomId); });
+    return pending;
+  }
+  async function performRefreshAll() {
+    if (!viewer || !api.list) return;
+    const currentEpoch = epoch;
+    const version = ++listVersion;
+    listLoading = true;
+    const roomVersions = new Map([...rooms].map(([id, row]) => [id, row.version]));
+    try {
+      const result = await api.list();
+      if (currentEpoch !== epoch || version !== listVersion) return;
+      const entries = new Map(result.preferences.map((entry) => [normalizeKey(entry.room_id), entry]));
+      for (const id of new Set([...rooms.keys(), ...entries.keys()])) {
+        const row = state(id);
+        if (row.version !== (roomVersions.get(id) ?? 0) || row.loading || row.busy) continue;
+        if (!entries.has(id) && result.truncated) continue;
+        row.preference = entries.get(id) ?? { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+        row.ready = true;
+        row.error = '';
+      }
+    } catch (error) {
+      if (currentEpoch !== epoch || version !== listVersion) return;
+      for (const [id, row] of rooms) {
+        if (row.version !== (roomVersions.get(id) ?? 0) || row.loading || row.busy) continue;
+        if (!row.ready) row.preference = { ...DEFAULT_ROOM_NOTIFICATION_PREFERENCE };
+        row.ready = true;
+        row.error = error instanceof Error ? error.message : 'Notification settings could not be loaded.';
+      }
+    }
+    if (version === listVersion && currentEpoch === epoch) listLoading = false;
+    changed();
+  }
+  function refreshAll() {
+    const pending = performRefreshAll();
+    pendingList = pending;
+    void pending.then(() => { if (pendingList === pending) pendingList = null; });
+    return pending;
+  }
+  async function update(roomId, change) {
+    roomId = normalizeKey(roomId);
+    if (!viewer || !api.put) throw new Error('Sign in to manage your room notifications.');
+    const row = state(roomId);
+    if (row.busy) return;
+    row.busy = true;
+    row.loading = false;
+    row.version++;
+    listVersion++;
+    listLoading = false;
+    const currentEpoch = epoch;
+    changed();
+    try {
+      const preference = await api.put(roomId, change);
+      if (currentEpoch !== epoch) return;
+      row.preference = preference;
+      row.ready = true;
+      row.error = '';
+    } catch (error) {
+      if (currentEpoch !== epoch) return;
+      row.error = error instanceof Error ? error.message : 'Notification settings could not be saved.';
+    } finally {
+      if (currentEpoch === epoch) { row.busy = false; changed(); }
+    }
+  }
+  function allows(roomId, text, now = Date.now()) {
+    const row = state(roomId);
+    if ((row.loading || listLoading) && !row.ready) return false;
+    return allowsRoomNotification(row.preference, text, viewer?.login, now);
+  }
+  async function allowsAfterRead(roomId, text) {
+    roomId = normalizeKey(roomId);
+    const currentEpoch = epoch;
+    while (currentEpoch === epoch && !state(roomId).ready) {
+      const pending = pendingReads.get(roomId) ?? pendingList;
+      if (!pending) break;
+      await pending;
+    }
+    return currentEpoch === epoch && allows(roomId, text);
+  }
+  return { setViewer, state, refresh, refreshAll, update, allows, allowsAfterRead, signedIn: () => Boolean(viewer) };
+}

package/shared/room-notification-preferences.d.mts

@@ -0,0 +1,17 @@
+export type RoomNotificationLevel = 'all' | 'mentions' | 'muted';
+export interface RoomNotificationPreference {
+  level: RoomNotificationLevel;
+  snoozed_until: string | null;
+}
+export interface RoomNotificationPreferenceEntry extends RoomNotificationPreference { room_id: string }
+export interface RoomNotificationPreferenceList { preferences: RoomNotificationPreferenceEntry[]; truncated: boolean }
+export type RoomNotificationPreferenceChange = Partial<RoomNotificationPreference>;
+export type RoomNotificationSnoozePreset = '1h' | '8h' | 'tomorrow';
+export declare const ROOM_NOTIFICATION_LEVELS: readonly RoomNotificationLevel[];
+export declare const DEFAULT_ROOM_NOTIFICATION_PREFERENCE: Readonly<RoomNotificationPreference>;
+export declare const PERSON_MENTION_START: string;
+export declare const PERSON_MENTION_END: string;
+export declare function mentionsPerson(text: unknown, login: string | null | undefined): boolean;
+export declare function roomNotificationsSuppressed(preference: RoomNotificationPreference | null | undefined, now?: number): boolean;
+export declare function allowsRoomNotification(preference: RoomNotificationPreference | null | undefined, text: unknown, login: string | null | undefined, now?: number): boolean;
+export declare function roomNotificationSnoozeUntil(preset: RoomNotificationSnoozePreset, now?: Date): string;

package/shared/room-notification-preferences.mjs

@@ -0,0 +1,34 @@
+export const ROOM_NOTIFICATION_LEVELS = ['all', 'mentions', 'muted'];
+export const DEFAULT_ROOM_NOTIFICATION_PREFERENCE = Object.freeze({ level: 'all', snoozed_until: null });
+// Shared with PostgreSQL's regex predicate. A final sentence period is punctuation;
+// a dot followed by a handle character is part of a longer handle.
+export const PERSON_MENTION_START = '(^|[^A-Za-z0-9_./@:-])@';
+export const PERSON_MENTION_END = '(?![A-Za-z0-9_/@:-]|\\.[A-Za-z0-9_])';
+
+export function mentionsPerson(text, login) {
+  if (typeof login !== 'string' || !login) return false;
+  const escaped = login.replace(/[^A-Za-z0-9_-]/g, '\\$&');
+  return new RegExp(PERSON_MENTION_START + escaped + PERSON_MENTION_END, 'i').test(String(text ?? ''));
+}
+
+export function roomNotificationsSuppressed(preference, now = Date.now()) {
+  return preference?.level === 'muted' || Date.parse(preference?.snoozed_until ?? '') > now;
+}
+
+export function allowsRoomNotification(preference, text, login, now = Date.now()) {
+  if (roomNotificationsSuppressed(preference, now)) return false;
+  return preference?.level !== 'mentions' || mentionsPerson(text, login);
+}
+
+export function roomNotificationSnoozeUntil(preset, now = new Date()) {
+  const date = new Date(now);
+  if (preset === 'tomorrow') {
+    date.setDate(date.getDate() + 1);
+    date.setHours(9, 0, 0, 0);
+  } else if (preset === '1h' || preset === '8h') {
+    date.setTime(date.getTime() + (preset === '1h' ? 1 : 8) * 60 * 60 * 1000);
+  } else {
+    throw new Error('Choose a snooze duration.');
+  }
+  return date.toISOString();
+}

package/shared/room-resource-invalidation.d.mts

@@ -5,12 +5,17 @@ export const ROOM_RESOURCE_AGENT_APPROVAL: "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION: "execution_delegation";
 /** What agents are waiting for changed; consumers re-read the room's wake rules. */
 export const ROOM_RESOURCE_WAKE_RULES: "wake_rules";
+/** A reaction was added or removed; consumers re-read the reactions of the messages they show. */
+export const ROOM_RESOURCE_MESSAGE_PINS: "message_pins";
+export const ROOM_RESOURCE_MESSAGE_REACTIONS: "message_reactions";
 /** Protocol-known references; consumers independently choose what they render. */
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES: readonly [
   "agent_work",
   "agent_approval",
   "execution_delegation",
   "wake_rules",
+  "message_reactions",
+  "message_pins",
 ];
 
 export type RoomResourceInvalidationResource =