letagents 0.12.34 → 0.12.36

package/shared/room-resource-invalidation.mjs

@@ -6,6 +6,10 @@ export const ROOM_RESOURCE_AGENT_WORK = "agent_work";
 export const ROOM_RESOURCE_AGENT_APPROVAL = "agent_approval";
 export const ROOM_RESOURCE_EXECUTION_DELEGATION = "execution_delegation";
 export const ROOM_RESOURCE_WAKE_RULES = "wake_rules";
+// Someone added or removed an emoji reaction. Consumers re-read the reactions
+// of the messages they show; the pointer never says which message changed.
+export const ROOM_RESOURCE_MESSAGE_PINS = "message_pins";
+export const ROOM_RESOURCE_MESSAGE_REACTIONS = "message_reactions";
 // Protocol-known references. Each consumer still decides which surfaces, if
 // any, react to a supported pointer.
 export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
@@ -13,6 +17,8 @@ export const ROOM_RESOURCE_INVALIDATION_RESOURCES = [
   ROOM_RESOURCE_AGENT_APPROVAL,
   ROOM_RESOURCE_EXECUTION_DELEGATION,
   ROOM_RESOURCE_WAKE_RULES,
+  ROOM_RESOURCE_MESSAGE_REACTIONS,
+  ROOM_RESOURCE_MESSAGE_PINS,
 ];
 
 function exactKeys(value, keys) {

package/shared/room-settings.d.mts

@@ -46,3 +46,19 @@ export declare function estimateRoomAgentGuidelineTokens(value: unknown): number
 export declare function normalizeGitHubRoomChatEventKinds(value: unknown): GitHubRoomChatEventKind[] | null;
 /** The kind a repository event is filed under, or null when it has none. */
 export declare function githubRoomChatEventKind(event: { kind?: string } | null | undefined): GitHubRoomChatEventKind | null;
+
+export type RoomAgentReplyOrder = "sequential" | "parallel";
+export declare const ROOM_AGENT_REPLY_ORDERS: readonly RoomAgentReplyOrder[];
+export declare const DEFAULT_ROOM_AGENT_REPLY_ORDER: RoomAgentReplyOrder;
+
+export interface RoomAgentReplyOrderSetting {
+  room_id: string;
+  /** The order that applies; "parallel" when the room has not chosen. */
+  order: RoomAgentReplyOrder;
+  /** Whether a room admin chose it, rather than the default applying. */
+  chosen: boolean;
+  can_manage: boolean;
+}
+
+/** A known order, or null when the input is not one. */
+export declare function normalizeRoomAgentReplyOrder(value: unknown): RoomAgentReplyOrder | null;

package/shared/room-settings.mjs

@@ -106,3 +106,17 @@ export function githubRoomChatEventKind(event) {
       return null;
   }
 }
+
+/**
+ * How agents answer a message that activates several of them at once (a
+ * broadcast, or the small-room fallback). "parallel" — the default when a
+ * room has not chosen — wakes them all together; "sequential", which a room
+ * admin turns on, gives each agent a turn after the one before has answered.
+ */
+export const ROOM_AGENT_REPLY_ORDERS = Object.freeze(["sequential", "parallel"]);
+export const DEFAULT_ROOM_AGENT_REPLY_ORDER = "parallel";
+
+/** A known order, or null when the input is not one. */
+export function normalizeRoomAgentReplyOrder(value) {
+  return ROOM_AGENT_REPLY_ORDERS.includes(value) ? value : null;
+}

package/shared/room-typing.d.mts

@@ -0,0 +1,18 @@
+export const ROOM_TYPING: 'room_typing_v1';
+export const TYPING: Readonly<{ ttl: number; interval: number; sweep: number; sources: number; people: number; entries: number; name: number }>;
+export interface TypingReport { client_id: string; sequence: number; typing: boolean; ttl_ms: number }
+export interface TypingSignal extends TypingReport { room_id: string; account_id: string; name: string; expires_at: number }
+export function parseTypingReport(value: unknown): TypingReport | null;
+export function parseTypingSignal(value: unknown): TypingSignal | null;
+export function createTypingSender(options: {
+  send: (report: TypingReport) => unknown; clientId: string; now?: () => number;
+  schedule?: (callback: () => void, ms: number) => any; cancel?: (timer: any) => void;
+}): { input(nonempty: boolean): void; stop(): void };
+export function createTypingReceiver(now?: () => number): {
+  receive(raw: unknown, self: string | null): void; clear(): void; names(): string[]; label(): string; nextExpiry(): number | null;
+};
+export function typingLabel(names: readonly string[]): string;
+export function typingSentence(names: readonly string[]): Array<{ text: string; name: boolean }>;
+export function createTypingDisplay(update: (label: string, names: string[]) => void, clock?: {
+  now?: () => number; schedule?: (callback: () => void, ms: number) => any; cancel?: (timer: any) => void;
+}): { receive(raw: unknown, self: string | null): void; clear(): void };

package/shared/room-typing.mjs

@@ -0,0 +1,129 @@
+export const ROOM_TYPING = 'room_typing_v1';
+export const TYPING = Object.freeze({ ttl: 5000, interval: 2500, sweep: 1000, sources: 4, people: 512, entries: 10000, name: 80 });
+
+export function parseTypingReport(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const { client_id, sequence, typing, ttl_ms } = value;
+  if (Object.keys(value).sort().join() !== 'client_id,sequence,ttl_ms,typing'
+    || typeof client_id !== 'string' || !/^[a-zA-Z0-9_-]{16,64}$/.test(client_id)
+    || !Number.isSafeInteger(sequence) || sequence < 1 || typeof typing !== 'boolean'
+    || !Number.isInteger(ttl_ms) || ttl_ms < 0 || ttl_ms > TYPING.ttl
+    || typing !== (ttl_ms > 0)) return null;
+  return { client_id, sequence, typing, ttl_ms };
+}
+
+export function parseTypingSignal(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const { room_id, account_id, name, expires_at, ...report } = value;
+  if (!parseTypingReport(report) || ![room_id, account_id, name].every(v => typeof v === 'string' && v.length > 0)
+    || room_id.length > 512 || account_id.length > 128 || name.length > TYPING.name
+    || !Number.isSafeInteger(expires_at)) return null;
+  return value;
+}
+
+/** No drafts enter this controller: input is only a nonempty/empty bit. */
+export function createTypingSender({ send, clientId, now = Date.now, schedule = setTimeout, cancel = clearTimeout }) {
+  let sequence = 0, lastSent = -Infinity, lastInput = 0, active = false, reported = false, dirty = false, timer = null;
+  function report(typing) {
+    lastSent = now();
+    reported = typing;
+    dirty = false;
+    try {
+      void Promise.resolve(send({ client_id: clientId, sequence: ++sequence, typing,
+        ttl_ms: typing ? Math.max(1, TYPING.ttl - (now() - lastInput)) : 0 })).catch(() => {});
+    } catch { /* Reporting cannot interrupt composing, sending, or cleanup. */ }
+  }
+  function stop() {
+    if (timer !== null) cancel(timer);
+    timer = null;
+    if (reported) report(false);
+    active = false;
+  }
+  function tick() {
+    timer = null;
+    if (now() - lastInput >= TYPING.ttl) return stop();
+    if (dirty && now() - lastSent >= TYPING.interval) report(true);
+    timer = schedule(tick, Math.min(TYPING.interval, TYPING.ttl - (now() - lastInput)));
+  }
+  return {
+    input(nonempty) {
+      if (!nonempty) return stop();
+      lastInput = now();
+      dirty = true;
+      if (!active) {
+        active = true;
+        if (now() - lastSent >= TYPING.interval) report(true);
+      }
+      if (timer === null) timer = schedule(tick, TYPING.interval);
+    },
+    stop,
+  };
+}
+
+/** Plain-text sentence for assistive technology and compact surfaces. */
+export function typingLabel(names) {
+  if (names.length > 2) return 'Several people are typing…';
+  return names.length ? `${names.join(' and ')} ${names.length === 1 ? 'is' : 'are'} typing…` : '';
+}
+
+/** The same sentence as parts, so a view can emphasise names without building HTML. */
+export function typingSentence(names) {
+  const name = text => ({ text, name: true }), plain = text => ({ text, name: false });
+  if (names.length === 1) return [name(names[0]), plain(' is typing')];
+  if (names.length === 2) return [name(names[0]), plain(' and '), name(names[1]), plain(' are typing')];
+  if (names.length < 3) return [];
+  const others = names.length - 2;
+  return [name(names[0]), plain(', '), name(names[1]), plain(` and ${others} ${others === 1 ? 'other' : 'others'} are typing`)];
+}
+
+/** Sequence guards survive stops briefly; no snapshot or replay. */
+export function createTypingReceiver(now = Date.now) {
+  const sources = new Map();
+  return {
+    receive(raw, self) {
+      const value = parseTypingSignal(raw);
+      if (!value || value.account_id === self) return;
+      const key = `${value.account_id}:${value.client_id}`;
+      const previous = sources.get(key);
+      if (previous && previous.sequence >= value.sequence) return;
+      if (!previous && sources.size >= TYPING.people * TYPING.sources) return;
+      sources.set(key, { ...value, until: now() + Math.min(value.ttl_ms, TYPING.ttl), forget: now() + TYPING.ttl });
+    },
+    clear() { sources.clear(); },
+    nextExpiry() {
+      let earliest = Infinity;
+      for (const value of sources.values()) {
+        if (value.typing && value.until > now()) earliest = Math.min(earliest, value.until);
+      }
+      return Number.isFinite(earliest) ? earliest : null;
+    },
+    /** One name per account, in a stable order, so a row does not reshuffle between refreshes. */
+    names() {
+      const people = new Map();
+      for (const [key, value] of sources) {
+        if (value.forget <= now()) sources.delete(key);
+        else if (value.typing && value.until > now()) people.set(value.account_id, value.name);
+      }
+      return [...people].sort(([a], [b]) => a.localeCompare(b)).map(([, name]) => name);
+    },
+    label() { return typingLabel(this.names()); },
+  };
+}
+
+/** A single receiver timeout, and no timer at all when nobody is typing. */
+export function createTypingDisplay(update, { now = Date.now, schedule = setTimeout, cancel = clearTimeout } = {}) {
+  const receiver = createTypingReceiver(now);
+  let timer = null;
+  function refresh() {
+    if (timer !== null) cancel(timer);
+    timer = null;
+    const names = receiver.names();
+    update(typingLabel(names), names);
+    const expiry = receiver.nextExpiry();
+    if (expiry !== null) timer = schedule(refresh, Math.max(0, expiry - now()));
+  }
+  return {
+    receive(raw, self) { receiver.receive(raw, self); refresh(); },
+    clear() { receiver.clear(); refresh(); },
+  };
+}

package/shared/room-unread-client.ts

@@ -0,0 +1,128 @@
+import { computed, nextTick, onMounted, onScopeDispose, ref, watch, type Ref, type InjectionKey } from "vue";
+import { canClearUnreadBookmark, createRoomUnreadStore } from "./room-unread.mjs";
+
+export function createRoomUnreadClient(namespace: string) {
+  const account = ref<string | null>(null);
+  const revision = ref(0);
+  const visit = ref({ room: "", account: null as string | null, revision: null as string | null, generation: 0, dividerId: null as string | null });
+  const store = createRoomUnreadStore({
+    namespace, storage: () => window.localStorage,
+    changed: () => { revision.value++; },
+  });
+  if (typeof window !== "undefined") window.addEventListener("storage", event => {
+    if (store.acceptsStorageEvent(event.key)) revision.value++;
+  });
+  function enter(room: string | null | undefined) {
+    room = (room ?? "").trim().toLowerCase();
+    if (visit.value.room === room && visit.value.account === account.value) return;
+    visit.value = { room, account: account.value, revision: store.get(account.value, room)?.revision ?? null, generation: visit.value.generation + 1, dividerId: null };
+  }
+  watch(account, () => enter(visit.value.room), { flush: "sync" });
+  return {
+    account, visit, enter,
+    get(room: string | null | undefined) {
+      void revision.value;
+      return store.get(account.value, room);
+    },
+    mark: (room: string | null | undefined, messageId: string) => store.mark(account.value, room, messageId),
+    clear: (room: string | null | undefined, expected: string) => store.clear(account.value, room, expected),
+  };
+}
+export type RoomUnreadClient = ReturnType<typeof createRoomUnreadClient>;
+export const unreadMenuKey: InjectionKey<{ client: RoomUnreadClient; room: Readonly<Ref<string | null | undefined>> }> = Symbol("room-unread-menu");
+
+export function useUnreadTimeline(options: {
+  client: RoomUnreadClient;
+  room: Readonly<Ref<string | null | undefined>>;
+  active: Readonly<Ref<boolean>>;
+  ready: Readonly<Ref<boolean>>;
+  element: Ref<HTMLElement | null>;
+  reveal(messageId: string): Promise<boolean>;
+  bottom(reading?: boolean): void;
+}) {
+  const { client } = options;
+  const bookmark = computed(() => client.get(options.room.value));
+  const enteredRevision = ref<string | null>(null);
+  const revealed = ref(false);
+  let generation = 0;
+  let started = false;
+  let reading = false;
+  let automaticScroll = false;
+  let mounted = false;
+  const dividerId = computed(() => client.visit.value.room === (options.room.value ?? "").trim().toLowerCase()
+    ? client.visit.value.dividerId : null);
+
+  function checkRead() {
+    const el = options.element.value;
+    if (!el || !options.active.value || automaticScroll) return;
+    if (canClearUnreadBookmark({
+      enteredRevision: enteredRevision.value, current: bookmark.value, revealed: revealed.value,
+      atBottom: el.scrollHeight - el.clientHeight - el.scrollTop < 60,
+      visible: document.visibilityState === "visible", focused: document.hasFocus(),
+    })) client.clear(options.room.value, enteredRevision.value!);
+  }
+  async function open() {
+    if (!mounted || started || !options.active.value || !options.ready.value) return;
+    started = true;
+    const mark = bookmark.value;
+    if (!mark || mark.revision !== enteredRevision.value) return;
+    const currentGeneration = generation;
+    const found = await options.reveal(mark.messageId);
+    if (generation !== currentGeneration || bookmark.value?.revision !== mark.revision) return;
+    revealed.value = found;
+    automaticScroll = false;
+    if (found) client.visit.value.dividerId = mark.messageId;
+    await nextTick();
+    if (generation !== currentGeneration) return;
+    if (!found) options.bottom();
+    else checkRead(); // Later visit already at the bottom, visible and focused.
+  }
+  watch(() => [options.room.value, client.visit.value.generation, options.active.value], () => {
+    generation++;
+    enteredRevision.value = options.active.value
+      && client.visit.value.room === (options.room.value ?? "").trim().toLowerCase()
+      ? client.visit.value.revision : null;
+    revealed.value = false;
+    started = false;
+    reading = false;
+    automaticScroll = false;
+    void nextTick(open);
+  }, { immediate: true, flush: "sync" });
+  watch(options.ready, () => { void nextTick(open); });
+
+  function input(event: Event) {
+    if (event instanceof KeyboardEvent && !["ArrowDown", "ArrowUp", "PageDown", "PageUp", "End", "Home", " "].includes(event.key)) return;
+    reading = true;
+    automaticScroll = false;
+    void nextTick(() => { if (reading) checkRead(); });
+  }
+  function scroll() { if (reading) checkRead(); }
+  function scrollEnd() { if (reading) checkRead(); reading = false; }
+  function programmaticScroll() { reading = false; automaticScroll = true; }
+  function jumpToLatest() {
+    options.bottom(true);
+    reading = true;
+    automaticScroll = false;
+    void nextTick(() => { if (reading) checkRead(); });
+  }
+  onMounted(() => {
+    mounted = true;
+    const el = options.element.value;
+    for (const event of ["wheel", "touchmove", "pointerdown", "keydown"]) el?.addEventListener(event, input, { passive: true });
+    el?.addEventListener("scroll", scroll);
+    el?.addEventListener("scrollend", scrollEnd);
+    window.addEventListener("focus", checkRead);
+    document.addEventListener("visibilitychange", checkRead);
+    void nextTick(open);
+  });
+  onScopeDispose(() => {
+    generation++;
+    const el = options.element.value;
+    for (const event of ["wheel", "touchmove", "pointerdown", "keydown"]) el?.removeEventListener(event, input);
+    el?.removeEventListener("scroll", scroll);
+    el?.removeEventListener("scrollend", scrollEnd);
+    window.removeEventListener("focus", checkRead);
+    document.removeEventListener("visibilitychange", checkRead);
+  });
+  return { dividerId, programmaticScroll, jumpToLatest };
+}

package/shared/room-unread.d.mts

@@ -0,0 +1,25 @@
+export interface RoomUnreadBookmark {
+  room: string;
+  messageId: string;
+  revision: string;
+  markedAt: number;
+}
+export function unreadRoomKey(room: string | null | undefined): string;
+export function createRoomUnreadStore(options: {
+  storage(): Pick<Storage, "getItem" | "setItem">;
+  namespace: string;
+  changed?(): void;
+}): {
+  get(account: string | null, room: string | null | undefined): RoomUnreadBookmark | null;
+  mark(account: string | null, room: string | null | undefined, messageId: string): RoomUnreadBookmark | null;
+  clear(account: string | null, room: string | null | undefined, revision: string): boolean;
+  acceptsStorageEvent(key: string | null): boolean;
+};
+export function canClearUnreadBookmark(input: {
+  enteredRevision: string | null;
+  current: RoomUnreadBookmark | null;
+  revealed: boolean;
+  atBottom: boolean;
+  visible: boolean;
+  focused: boolean;
+}): boolean;

package/shared/room-unread.mjs

@@ -0,0 +1,57 @@
+const MAX_ROOMS = 500;
+export const unreadRoomKey = (room) => String(room ?? "").trim().toLowerCase();
+
+// This is a personal local bookmark, never receipt or notification evidence.
+// Resolve storage inside each try block: even the localStorage getter can throw.
+export function createRoomUnreadStore({ storage, namespace, changed = () => {} }) {
+  const key = (account) => `${namespace}:${encodeURIComponent(account)}`;
+  function read(account) {
+    if (!account) return [];
+    try {
+      const rows = JSON.parse(storage().getItem(key(account)) || "[]");
+      return Array.isArray(rows) ? rows.filter(row => row
+        && typeof row.room === "string" && row.room
+        && typeof row.messageId === "string" && row.messageId
+        && typeof row.revision === "string" && row.revision
+        && Number.isFinite(row.markedAt)).slice(-MAX_ROOMS) : [];
+    } catch { return []; }
+  }
+  function write(account, rows) {
+    try {
+      storage().setItem(key(account), JSON.stringify(rows.slice(-MAX_ROOMS)));
+      changed();
+      return true;
+    } catch { changed(); return false; }
+  }
+  function get(account, room) {
+    return read(account).find(row => row.room === unreadRoomKey(room)) ?? null;
+  }
+  return {
+    get,
+    mark(account, room, messageId) {
+      room = unreadRoomKey(room);
+      if (!account || !room || !messageId || messageId.startsWith("pending:")) return null;
+      const markedAt = Date.now();
+      let revision = `${markedAt}-${Math.random()}`;
+      try { revision = globalThis.crypto?.randomUUID?.() ?? revision; } catch { /* Plain HTTP may lack secure crypto. */ }
+      const row = { room, messageId, markedAt, revision };
+      return write(account, [...read(account).filter(item => item.room !== room), row]) ? row : null;
+    },
+    clear(account, room, revision) {
+      const rows = read(account);
+      const current = rows.find(row => row.room === unreadRoomKey(room));
+      if (!current || current.revision !== revision) return false;
+      return write(account, rows.filter(row => row !== current));
+    },
+    acceptsStorageEvent(eventKey) {
+      return eventKey === null || eventKey.startsWith(namespace + ":");
+    },
+  };
+}
+
+// Capture once at entry, before loading history. A mark made during this visit
+// (including one from another tab) can never match this captured revision.
+export function canClearUnreadBookmark({ enteredRevision, current, revealed, atBottom, visible, focused }) {
+  return Boolean(enteredRevision && current?.revision === enteredRevision
+    && revealed && atBottom && visible && focused);
+}

package/shared/room-unread.test.mjs

@@ -0,0 +1,91 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createRoomUnreadStore, canClearUnreadBookmark } from "./room-unread.mjs";
+
+test("bookmarks persist per account and room, without changing existing markers or receipt evidence", () => {
+  const data = new Map([["legacy-markers", '{"a":"msg_9"}'], ["receipts", '{"a":[1,9]}']]);
+  const storage = () => ({ getItem: key => data.get(key) ?? null, setItem: (key, value) => data.set(key, value) });
+  const store = createRoomUnreadStore({ storage, namespace: "test" });
+  const a = store.mark("alice", " RoomA ", "msg_3");
+  store.mark("bob", "rooma", "msg_5");
+  store.mark("alice", "roomb", "msg_7");
+  const reload = createRoomUnreadStore({ storage, namespace: "test" });
+  assert.equal(reload.get("alice", "rooma").revision, a.revision);
+  assert.equal(reload.get("bob", "rooma").messageId, "msg_5");
+  assert.equal(reload.get("alice", "roomb").messageId, "msg_7");
+  assert.equal(reload.get("other", "rooma"), null);
+  assert.equal(data.get("legacy-markers"), '{"a":"msg_9"}');
+  assert.equal(data.get("receipts"), '{"a":[1,9]}');
+});
+
+test("a stale clear re-reads storage and cannot erase a newer mark from another window", () => {
+  const data = new Map();
+  const storage = () => ({ getItem: key => data.get(key) ?? null, setItem: (key, value) => data.set(key, value) });
+  const first = createRoomUnreadStore({ storage, namespace: "test" });
+  const second = createRoomUnreadStore({ storage, namespace: "test" });
+  const old = first.mark("a", "room", "msg_1");
+  const newer = second.mark("a", "room", "msg_2");
+  assert.equal(first.clear("a", "room", old.revision), false);
+  assert.deepEqual(first.get("a", "room"), newer);
+  assert.equal(second.clear("a", "room", newer.revision), true);
+  assert.equal(first.get("a", "room"), null);
+});
+
+test("marking works when randomUUID is absent or unavailable outside a secure context", (t) => {
+  const data = new Map();
+  const store = createRoomUnreadStore({
+    namespace: "test",
+    storage: () => ({ getItem: key => data.get(key) ?? null, setItem: (key, value) => data.set(key, value) }),
+  });
+  const original = Object.getOwnPropertyDescriptor(globalThis, "crypto");
+  t.after(() => Object.defineProperty(globalThis, "crypto", original));
+  for (const crypto of [undefined, {}, { randomUUID() { throw Error("unavailable"); } }]) {
+    Object.defineProperty(globalThis, "crypto", { configurable: true, value: crypto });
+    const first = store.mark("alice", "room", "msg_1");
+    const second = store.mark("alice", "room", "msg_2");
+    assert.ok(first?.revision);
+    assert.ok(second?.revision);
+    assert.notEqual(second.revision, first.revision);
+    assert.equal(store.clear("alice", "room", first.revision), false);
+    assert.deepEqual(store.get("alice", "room"), second);
+  }
+});
+
+test("storage getter, read, write and malformed data failures do not escape or create a bookmark", () => {
+  const fail = () => { throw new Error("blocked"); };
+  for (const storage of [fail, () => ({ getItem: fail, setItem: fail }), () => ({ getItem: () => null, setItem: fail })]) {
+    const store = createRoomUnreadStore({ storage, namespace: "test" });
+    assert.equal(store.get("a", "room"), null);
+    assert.equal(store.mark("a", "room", "msg_1"), null);
+    assert.equal(store.clear("a", "room", "r"), false);
+  }
+  for (const value of ["bad JSON", "null", "{}", '[null,{},{"room":"x"}]']) {
+    const store = createRoomUnreadStore({ storage: () => ({ getItem: () => value, setItem() {} }), namespace: "test" });
+    assert.equal(store.get("a", "x"), null);
+  }
+});
+
+test("500 most recently marked rooms are retained; replacing one does not consume another slot", () => {
+  let raw = null;
+  const store = createRoomUnreadStore({ namespace: "test", storage: () => ({ getItem: () => raw, setItem: (_, value) => { raw = value; } }) });
+  for (let i = 0; i < 501; i++) store.mark("a", "room" + i, "msg_" + i);
+  assert.equal(store.get("a", "room0"), null);
+  assert.equal(store.get("a", "room1").messageId, "msg_1");
+  store.mark("a", "room1", "msg_900");
+  store.mark("a", "room501", "msg_501");
+  assert.equal(store.get("a", "room2"), null);
+  assert.equal(store.get("a", "room1").messageId, "msg_900");
+  assert.equal(JSON.parse(raw).length, 500);
+});
+
+test("only a revealed bookmark from entry can clear at the visible, focused bottom", () => {
+  const current = { revision: "old" };
+  const eligible = { enteredRevision: "old", current, revealed: true, atBottom: true, visible: true, focused: true };
+  assert.equal(canClearUnreadBookmark(eligible), true);
+  for (const key of ["revealed", "atBottom", "visible", "focused"]) {
+    assert.equal(canClearUnreadBookmark({ ...eligible, [key]: false }), false, key);
+  }
+  assert.equal(canClearUnreadBookmark({ ...eligible, enteredRevision: null }), false);
+  assert.equal(canClearUnreadBookmark({ ...eligible, current: { revision: "new" } }), false);
+  assert.equal(canClearUnreadBookmark({ ...eligible, current: null }), false);
+});

package/shared/rooms/RoomsDirectory.vue

@@ -271,7 +271,7 @@
                 </template></svg
             ></span>
             <span class="rooms-entry-copy"
-              ><span class="rooms-entry-title">{{ room.title }}</span
+              ><span class="rooms-entry-title">{{ room.title }}<span v-if="room.hasUnread" class="rooms-unread-dot" aria-label="Unread messages"> ●</span></span
               ><span class="rooms-entry-description"
                 ><span class="rooms-mobile-kind"
                   >{{ roomKindLabel(room) }} · </span

package/shared/rooms/directory.ts

@@ -1,6 +1,7 @@
 export interface DirectoryRoom {
   id: string
   title: string
+  hasUnread?: boolean
   kind: 'topic' | 'task' | 'branch'
   kindLabel?: string
   closed: boolean

package/shared/slash-commands.d.mts

@@ -0,0 +1,31 @@
+export type SlashPlatform = 'desktop' | 'web';
+export interface SlashCommand {
+  readonly name: 'task' | 'search' | 'agent';
+  readonly usage: string;
+  readonly description: string;
+  readonly argument: 'required' | 'none';
+  readonly platforms: readonly SlashPlatform[];
+}
+export interface SlashInputContext {
+  text: string;
+  platform: SlashPlatform;
+  hasAttachments?: boolean;
+  isReply?: boolean;
+  menuDismissed?: boolean;
+  selectedCommandIndex?: number;
+}
+export type SlashResolution =
+  | { kind: 'none' }
+  | { kind: 'menu'; commands: readonly SlashCommand[] }
+  | { kind: 'invalid'; command: SlashCommand; hint: string }
+  | { kind: 'execute'; command: SlashCommand; argument: string };
+export type ComposerSubmitDecision =
+  | { action: 'send_message' }
+  | { action: 'complete_command'; text: string }
+  | { action: 'show_hint'; hint: string }
+  | { action: 'execute_command'; command: SlashCommand; argument: string };
+export declare const SLASH_COMMANDS: readonly SlashCommand[];
+export declare function getSlashCommands(platform: SlashPlatform): readonly SlashCommand[];
+export declare function resolveSlashInput(context: SlashInputContext): SlashResolution;
+export declare function completeSlashCommand(command: SlashCommand): string;
+export declare function decideComposerSubmitAction(context: SlashInputContext): ComposerSubmitDecision;

package/shared/slash-commands.mjs

@@ -0,0 +1,48 @@
+// Local composer commands. Unknown slash-prefixed text remains an ordinary message.
+export const SLASH_COMMANDS = Object.freeze([
+  Object.freeze({ name: 'task', usage: '/task <title>', description: 'Create a task on the board', argument: 'required', platforms: ['desktop', 'web'] }),
+  Object.freeze({ name: 'search', usage: '/search <query>', description: 'Search messages in this room', argument: 'required', platforms: ['desktop', 'web'] }),
+  Object.freeze({ name: 'agent', usage: '/agent', description: 'Add an agent to this room', argument: 'none', platforms: ['desktop'] }),
+]);
+
+export function getSlashCommands(platform) {
+  return SLASH_COMMANDS.filter(command => command.platforms.includes(platform));
+}
+
+export function resolveSlashInput({ text, platform, hasAttachments, isReply, menuDismissed }) {
+  if (!text.startsWith('/') || /[\r\n]/.test(text) || hasAttachments || isReply || menuDismissed) {
+    return { kind: 'none' };
+  }
+  const match = /^\/([^\s]*)(?:\s+(.*))?$/.exec(text);
+  if (!match) return { kind: 'none' };
+  const name = match[1].toLowerCase();
+  const commands = getSlashCommands(platform);
+  const command = commands.find(candidate => candidate.name === name);
+  if (!command) {
+    const matches = match[2] === undefined ? commands.filter(candidate => candidate.name.startsWith(name)) : [];
+    return matches.length ? { kind: 'menu', commands: matches } : { kind: 'none' };
+  }
+  const argument = (match[2] ?? '').trim();
+  if (command.argument === 'required' && !argument) {
+    return { kind: 'invalid', command, hint: command.name === 'task' ? 'Add a task title' : 'Add a search query' };
+  }
+  if (command.argument === 'none' && argument) {
+    return { kind: 'invalid', command, hint: '/agent does not take arguments' };
+  }
+  return { kind: 'execute', command, argument };
+}
+
+export function completeSlashCommand(command) {
+  return `/${command.name}${command.argument === 'required' ? ' ' : ''}`;
+}
+
+export function decideComposerSubmitAction(input) {
+  const resolution = resolveSlashInput(input);
+  if (resolution.kind === 'none') return { action: 'send_message' };
+  if (resolution.kind === 'menu') {
+    const command = resolution.commands[input.selectedCommandIndex ?? 0] ?? resolution.commands[0];
+    return { action: 'complete_command', text: completeSlashCommand(command) };
+  }
+  if (resolution.kind === 'invalid') return { action: 'show_hint', hint: resolution.hint };
+  return { action: 'execute_command', command: resolution.command, argument: resolution.argument };
+}

package/shared/slash-commands.test.mjs

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { decideComposerSubmitAction, getSlashCommands, resolveSlashInput } from './slash-commands.mjs';
+
+for (const platform of ['desktop', 'web']) {
+  test(`${platform}: registry and parser honor the composer command boundary`, () => {
+    assert.deepEqual(getSlashCommands(platform).map(command => command.name), platform === 'desktop' ? ['task', 'search', 'agent'] : ['task', 'search']);
+    assert.deepEqual(resolveSlashInput({ text: '/', platform }).commands.map(command => command.name), getSlashCommands(platform).map(command => command.name));
+    for (const [text, action] of [
+      ['/t', 'complete_command'], ['/se', 'complete_command'],
+      ['/task', 'show_hint'], ['/task \t ', 'show_hint'], ['/search ', 'show_hint'],
+      ['/task Build it', 'execute_command'], ['/search error 404', 'execute_command'],
+      ['/TASK\tTitle', 'execute_command'],
+      ['/agent', platform === 'desktop' ? 'execute_command' : 'send_message'],
+      ['/agent extra', platform === 'desktop' ? 'show_hint' : 'send_message'],
+      ['/usr/bin', 'send_message'], ['/tasker title', 'send_message'], ['/t title', 'send_message'],
+      [' /task title', 'send_message'], ['Hello /task title', 'send_message'],
+      ['/task first\nsecond', 'send_message'], ['/task title\r', 'send_message'],
+    ]) assert.equal(decideComposerSubmitAction({ text, platform }).action, action, text);
+    for (const flag of ['hasAttachments', 'isReply', 'menuDismissed']) {
+      assert.equal(decideComposerSubmitAction({ text: '/task Title', platform, [flag]: true }).action, 'send_message', flag);
+    }
+    assert.equal(decideComposerSubmitAction({ text: '/', platform, selectedCommandIndex: 1 }).text, '/search ');
+    assert.equal(decideComposerSubmitAction({ text: '/task  Keep  spacing ', platform }).argument, 'Keep  spacing');
+  });
+}