@openmarket/rooms-client 0.1.0

package/src/agent/room-context.ts

@@ -0,0 +1,351 @@
+/**
+ * The context spine for agent-native rooms.
+ *
+ * Two jobs, both about spending tokens on the ask and not on the room's whole
+ * history:
+ *  - resolve a conversational scope ("the last 200", "since 'ok new plan'",
+ *    "since my last message") to a concrete history cursor the agent fetches;
+ *  - render the per-room BRIEF (a generated, human-readable doc: purpose,
+ *    running summary, open threads, decisions, and every doc the room refers to
+ *    with its freshness) and assemble a turn's context in cheapest-first tiers,
+ *    stopping at a budget so a turn never eats the ledger.
+ *
+ * Pure and dependency-free so every rule is unit-pinned; the runtime supplies
+ * the live history, the LLM summary, and the doc writes.
+ */
+
+export interface HistoryEntry {
+  seq: number;
+  handle: string;
+  text: string;
+  /** Marks agent-authored posts in prompt renders (`@handle✦`). */
+  isAgent?: boolean;
+  /** The topic this message is filed into, when any ("" is the untopicked
+   *  lane and reads as unfiled). Lets the lane seed a topic-scoped slice. */
+  topicId?: string;
+  /** A sealed (end-to-end encrypted) entry. Its plaintext never reaches this
+   *  layer (the relay stores none); rendered as a locked placeholder so the
+   *  agent knows one exists without any content leaking into context. */
+  sealed?: boolean;
+}
+
+/** Lane seeding: how many recent messages a lane turn carries room-wide when
+ *  the whisper starts from the plain channel stream (today's behavior). */
+export const LANE_ROOM_WINDOW = 30;
+/** Lane seeding: how many of the topic's recent messages a lane turn carries
+ *  when the whisper starts from inside a topic. */
+export const LANE_TOPIC_WINDOW = 30;
+/** Lane seeding: the smaller room-wide window that rides ALONGSIDE a topic
+ *  slice so cross-topic references still resolve without a tool call. */
+export const LANE_SCOPED_ROOM_WINDOW = 10;
+
+/** The topic a lane turn is scoped to (the conversation the composer was in
+ *  when the whisper started). An empty topicId is the untopicked lane and
+ *  callers treat it as unscoped. */
+export interface LaneTopicScope {
+  topicId: string;
+  name: string;
+}
+
+/**
+ * Slice the loaded ledger into the lane's seed windows. Unscoped (plain
+ * channel whisper): the room-wide recent window, exactly as before. Scoped
+ * (whisper from inside a topic): that topic's recent slice (what exists, up
+ * to the window) PLUS a smaller room-wide window for cross-topic references.
+ * Entries arrive pre-filtered (no deleted rows, no empty text), oldest first.
+ */
+export function laneSeedWindows(
+  entries: ReadonlyArray<HistoryEntry>,
+  topic?: LaneTopicScope | null,
+): Pick<TieredContextInput, "recentWindow" | "topicWindow"> {
+  if (!topic?.topicId) {
+    return { recentWindow: renderRecentWindow(entries.slice(-LANE_ROOM_WINDOW)) };
+  }
+  const topicEntries = entries
+    .filter((entry) => entry.topicId === topic.topicId)
+    .slice(-LANE_TOPIC_WINDOW);
+  return {
+    recentWindow: renderRecentWindow(entries.slice(-LANE_SCOPED_ROOM_WINDOW)),
+    topicWindow: { name: topic.name, lines: renderRecentWindow(topicEntries) },
+  };
+}
+
+export type HistoryScope = (
+  | { kind: "count"; n: number }
+  | { kind: "sinceMarker"; marker: string }
+  | { kind: "sinceMyLast"; myHandle: string }
+  | { kind: "thread"; rootSeq: number }
+) & {
+  /** Restrict to one author's messages within the window ("from @henry"). */
+  author?: string;
+};
+
+export interface ResolvedScope {
+  /** Fetch messages with seq strictly greater than this (when present). */
+  sinceSeq?: number;
+  /** Cap the number of messages (when present). */
+  limit?: number;
+  /** For a thread scope: the root message to expand. */
+  threadRootSeq?: number;
+  /** Only this handle's messages count; the seq window itself is unchanged. */
+  author?: string;
+  /** A human label for the change note / prompt ("since 'ok new plan'"). */
+  label: string;
+}
+
+/** Parse a free-text scope argument into a structured scope. Accepts a bare
+ *  count ("200"), `last N`, `since <text or "quoted marker">`, `since me` /
+ *  `since my last`, or `thread <seq>`. A leading `from @handle` scopes to one
+ *  author and composes with the rest ("from @henry", "from @henry last 100",
+ *  "from @henry since 'ok new plan'"). Defaults to a recent count. */
+export function parseHistoryScope(arg: string | undefined, myHandle: string): HistoryScope {
+  const raw = (arg ?? "").trim();
+  if (raw.length === 0) return { kind: "count", n: 50 };
+
+  const from = /^from\s+@([\w.-]+)\s*/i.exec(raw);
+  if (from?.[1]) {
+    return { ...parseHistoryScope(raw.slice(from[0].length), myHandle), author: from[1] };
+  }
+
+  const lower = raw.toLowerCase();
+  const countOnly = /^(?:last\s+)?(\d{1,4})$/.exec(lower);
+  if (countOnly?.[1]) return { kind: "count", n: Number(countOnly[1]) };
+
+  if (lower === "since me" || lower === "since my last" || lower === "since my last message") {
+    return { kind: "sinceMyLast", myHandle };
+  }
+  const thread = /^thread\s+(\d{1,9})$/.exec(lower);
+  if (thread?.[1]) return { kind: "thread", rootSeq: Number(thread[1]) };
+
+  const since = /^since\s+(.+)$/i.exec(raw);
+  if (since?.[1]) {
+    const marker = since[1].trim().replace(/^["']|["']$/g, "");
+    return { kind: "sinceMarker", marker };
+  }
+  // A bare phrase is treated as a marker to find.
+  return { kind: "sinceMarker", marker: raw.replace(/^["']|["']$/g, "") };
+}
+
+/** Resolve a scope against the room's recent entries. Returns null when a
+ *  marker or my-last-message cannot be found (the caller reports it). An
+ *  author filter rides through: the window resolves the same way, and the
+ *  caller keeps only that handle's messages inside it. */
+export function resolveHistoryScope(
+  scope: HistoryScope,
+  entries: ReadonlyArray<HistoryEntry>,
+): ResolvedScope | null {
+  const base = resolveScopeWindow(scope, entries);
+  if (!base || !scope.author) return base;
+  const author = scope.author.replace(/^@/, "");
+  return { ...base, author, label: `${base.label} from @${author}` };
+}
+
+function resolveScopeWindow(
+  scope: HistoryScope,
+  entries: ReadonlyArray<HistoryEntry>,
+): ResolvedScope | null {
+  switch (scope.kind) {
+    case "count":
+      return { limit: Math.max(1, Math.min(scope.n, 500)), label: `the last ${scope.n}` };
+    case "thread":
+      return { threadRootSeq: scope.rootSeq, label: `thread at ${scope.rootSeq}` };
+    case "sinceMyLast": {
+      const mine = [...entries]
+        .filter((e) => e.handle.replace(/^@/, "") === scope.myHandle.replace(/^@/, ""))
+        .sort((a, b) => a.seq - b.seq)
+        .at(-1);
+      if (!mine) return null;
+      return { sinceSeq: mine.seq, label: "since your last message" };
+    }
+    case "sinceMarker": {
+      const needle = scope.marker.toLowerCase();
+      if (needle.length === 0) return null;
+      // The LAST message that matches, so "since 'X'" starts at the most recent
+      // occurrence, not an older stray mention.
+      const match = [...entries]
+        .sort((a, b) => a.seq - b.seq)
+        .reverse()
+        .find((e) => e.text.toLowerCase().includes(needle));
+      if (!match) return null;
+      // Inclusive of the marker message itself: fetch seq > (markerSeq - 1).
+      return { sinceSeq: match.seq - 1, label: `since "${scope.marker}"` };
+    }
+  }
+}
+
+/** `#btc` → `briefs/btc.md`. The brief for a room is a real doc in the space's
+ *  library, so it rides the sync to disk and can be linked and read like any
+ *  other note. */
+export function briefPath(roomName: string): string {
+  const slug =
+    roomName
+      .trim()
+      .replace(/^#/, "")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60) || "room";
+  return `briefs/${slug}.md`;
+}
+
+export interface BriefDocRef {
+  path: string;
+  headRev: number;
+  ageLabel: string;
+}
+
+export interface BriefInput {
+  room: string;
+  updatedAtLabel: string;
+  /** One or two paragraphs of running summary (LLM-written). */
+  summary: string;
+  openThreads: string[];
+  decisions: string[];
+  docs: BriefDocRef[];
+}
+
+/** Render the canonical brief markdown. Deterministic shell; the LLM only
+ *  supplies the summary/threads/decisions prose. */
+export function renderBrief(input: BriefInput): string {
+  const lines: string[] = [];
+  lines.push(`# Brief: ${input.room}`);
+  lines.push("");
+  lines.push(`> Auto-generated by the room agent, read-only. Updated ${input.updatedAtLabel}.`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(input.summary.trim() || "_No summary yet._");
+  lines.push("");
+  lines.push("## Open threads");
+  lines.push("");
+  if (input.openThreads.length === 0) lines.push("_None._");
+  else for (const t of input.openThreads) lines.push(`- ${t}`);
+  lines.push("");
+  lines.push("## Decisions");
+  lines.push("");
+  if (input.decisions.length === 0) lines.push("_None yet._");
+  else for (const d of input.decisions) lines.push(`- ${d}`);
+  lines.push("");
+  lines.push("## Docs in play");
+  lines.push("");
+  if (input.docs.length === 0) lines.push("_None referenced._");
+  else for (const d of input.docs) lines.push(`- \`${d.path}\` (r${d.headRev}, ${d.ageLabel})`);
+  lines.push("");
+  return lines.join("\n");
+}
+
+export interface TieredContextInput {
+  /** Tier 0: always included (tiny by design). */
+  brief?: string;
+  /** Tier 1: rolling compaction of older history, newest-relevant first. */
+  epochSummaries?: string[];
+  /** Tier 2a: the scoped topic's recent slice, oldest-to-newest, labeled with
+   *  the topic's name. Present only for topic-scoped lane turns; it outranks
+   *  the room-wide window in the budget because it IS the whisper's
+   *  conversation. */
+  topicWindow?: { name: string; lines: string[] };
+  /** Tier 2 (2b when a topic slice rides above it): the recent verbatim
+   *  window, oldest-to-newest. */
+  recentWindow?: string[];
+}
+
+export interface AssembledContext {
+  text: string;
+  includedTiers: Array<"brief" | "epochs" | "topic" | "recent">;
+  usedChars: number;
+}
+
+/**
+ * Assemble a turn's context cheapest-first within a character budget. The brief
+ * (tier 0) always goes in; epoch summaries (tier 1) and the recent window (tier
+ * 2) fill the remaining budget and STOP. This is the hard token-efficiency
+ * rule: a turn's cost scales with the budget, never with the room's history.
+ */
+export function assembleTieredContext(
+  input: TieredContextInput,
+  budgetChars = 8000,
+): AssembledContext {
+  const parts: string[] = [];
+  const includedTiers: AssembledContext["includedTiers"] = [];
+  let used = 0;
+
+  const brief = input.brief?.trim();
+  if (brief) {
+    parts.push(`## Room brief\n${brief}`);
+    includedTiers.push("brief");
+    used += brief.length;
+  }
+
+  const epochs = input.epochSummaries ?? [];
+  if (epochs.length > 0 && used < budgetChars) {
+    const chosen: string[] = [];
+    for (const e of epochs) {
+      if (used + e.length > budgetChars) break;
+      chosen.push(e);
+      used += e.length;
+    }
+    if (chosen.length > 0) {
+      parts.push(`## Earlier context\n${chosen.join("\n")}`);
+      includedTiers.push("epochs");
+    }
+  }
+
+  // Freshest-first fill shared by both message tiers: take lines from the
+  // end (newest) until the budget fills, keeping oldest-to-newest order.
+  const fillFreshest = (lines: string[]): string[] => {
+    const chosen: string[] = [];
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i] as string;
+      if (used + line.length > budgetChars) break;
+      chosen.unshift(line);
+      used += line.length;
+    }
+    return chosen;
+  };
+
+  const topic = input.topicWindow;
+  if (topic && topic.lines.length > 0 && used < budgetChars) {
+    const chosen = fillFreshest(topic.lines);
+    if (chosen.length > 0) {
+      parts.push(`## Recent messages in this topic: ⌗ ${topic.name}\n${chosen.join("\n")}`);
+      includedTiers.push("topic");
+    }
+  }
+
+  const recent = input.recentWindow ?? [];
+  if (recent.length > 0 && used < budgetChars) {
+    const chosen = fillFreshest(recent);
+    if (chosen.length > 0) {
+      // When a topic slice rides above, say plainly what this wider window is.
+      const header = input.topicWindow
+        ? "## Recent messages across the channel (all topics)"
+        : "## Recent messages";
+      parts.push(`${header}\n${chosen.join("\n")}`);
+      includedTiers.push("recent");
+    }
+  }
+
+  return { text: parts.join("\n\n"), includedTiers, usedChars: used };
+}
+
+/**
+ * Render history entries as prompt lines for the recent-window tier:
+ * `[seq] @handle: text`, one line per message, whitespace-flattened and
+ * clamped. The bracketed seq is the message's address: it is what
+ * om://msg/<room>/<seq> citations and room_history paging key on.
+ */
+export function renderRecentWindow(
+  entries: ReadonlyArray<HistoryEntry>,
+  opts: { clampChars?: number } = {},
+): string[] {
+  const clamp = Math.max(16, opts.clampChars ?? 240);
+  return entries.map((entry) => {
+    const handle = entry.handle.replace(/^@+/, "") || "unknown";
+    if (entry.sealed) {
+      return `[${entry.seq}] @${handle}${entry.isAgent ? "✦" : ""}: 🔒 sealed message (encrypted; content not available)`;
+    }
+    const flat = entry.text.replace(/\s+/g, " ").trim();
+    const text = flat.length > clamp ? `${flat.slice(0, clamp - 1)}…` : flat;
+    return `[${entry.seq}] @${handle}${entry.isAgent ? "✦" : ""}: ${text}`;
+  });
+}

package/src/agent/sidebar-model.ts

@@ -0,0 +1,235 @@
+import type { RoomMeta, RoomSpace } from "../types.js";
+
+/**
+ * Navigation data for the Discord-style sidebar: rooms grouped by space,
+ * DM conversations, and a heat-ranked "popular" tail of unjoined rooms.
+ *
+ * Unread semantics:
+ *  - Rooms the user has OPEN (a live context) are authoritative: the live
+ *    context's counter is injected and always wins.
+ *  - Unjoined rooms diff the server head sequence (headSeq, attached by the
+ *    backend room lists) against the user's read cursor. Missing data means
+ *    no badge, never a guess.
+ */
+export interface SidebarRoom {
+  name: string;
+  title: string;
+  spaceId: string | null;
+  category: string | null;
+  sortOrder: number;
+  access: RoomMeta["access"];
+  online: number;
+  heatScore: number;
+  headSeq: number | null;
+  lastReadSeq: number | null;
+  unread: number;
+  joined: boolean;
+  /** Topics dial from room meta. Absent reads as "allowed" since the
+   *  2026-07-12 dial-default flip; explicit "off" keeps topics inert. */
+  topicsPolicy: RoomMeta["topicsPolicy"] | null;
+}
+
+export interface SidebarDm {
+  username: string;
+  unread: number;
+}
+
+export interface SidebarSnapshot {
+  spaces: Array<{ space: RoomSpace; rooms: SidebarRoom[] }>;
+  unspaced: SidebarRoom[];
+  dms: SidebarDm[];
+  popular: SidebarRoom[];
+  globalReplyUnread: number;
+  fetchedAt: number;
+}
+
+export const EMPTY_SIDEBAR_SNAPSHOT: SidebarSnapshot = {
+  spaces: [],
+  unspaced: [],
+  dms: [],
+  popular: [],
+  globalReplyUnread: 0,
+  fetchedAt: 0,
+};
+
+const POPULAR_MAX = 6;
+
+export function computeRoomUnread(input: {
+  joinedUnread: number | null;
+  headSeq: number | null;
+  lastReadSeq: number | null;
+}): number {
+  if (input.joinedUnread !== null) return Math.max(0, input.joinedUnread);
+  if (input.headSeq === null || input.headSeq <= 0) return 0;
+  if (input.lastReadSeq === null) return 0;
+  return Math.max(0, input.headSeq - input.lastReadSeq);
+}
+
+export function buildSidebarSnapshot(input: {
+  rooms: RoomMeta[];
+  spaces: RoomSpace[];
+  readState: Record<string, number>;
+  dms: SidebarDm[];
+  globalReplyUnread: number;
+  joinedUnread: (roomName: string) => number | null;
+  now: number;
+}): SidebarSnapshot {
+  const toSidebarRoom = (room: RoomMeta): SidebarRoom => {
+    const name = room.name;
+    const joinedUnread = input.joinedUnread(name);
+    const headSeq = typeof room.headSeq === "number" ? room.headSeq : null;
+    const lastReadSeq = Object.hasOwn(input.readState, name) ? (input.readState[name] ?? 0) : null;
+    return {
+      name,
+      title: room.title || `#${name}`,
+      spaceId: room.spaceId ?? null,
+      category: room.category ?? null,
+      sortOrder: room.sortOrder ?? 0,
+      access: room.access,
+      online: room.onlineCount ?? room.heat?.onlineCount ?? 0,
+      heatScore: room.heat?.score ?? 0,
+      headSeq,
+      lastReadSeq,
+      unread: computeRoomUnread({ joinedUnread, headSeq, lastReadSeq }),
+      // Joined = an open context OR a server read cursor (you only get a
+      // cursor by having been in the room). This is what decides whether a
+      // room lives in your channel tree or in the POPULAR discovery shelf.
+      joined: joinedUnread !== null || lastReadSeq !== null,
+      topicsPolicy: room.topicsPolicy ?? null,
+    };
+  };
+
+  const rooms = input.rooms.map(toSidebarRoom);
+  const bySpace = new Map<string, SidebarRoom[]>();
+  const unspaced: SidebarRoom[] = [];
+  for (const room of rooms) {
+    if (room.spaceId) {
+      const list = bySpace.get(room.spaceId) ?? [];
+      list.push(room);
+      bySpace.set(room.spaceId, list);
+    } else {
+      unspaced.push(room);
+    }
+  }
+
+  const knownSpaces = new Map(input.spaces.map((space) => [space.spaceId, space]));
+  const spaces: SidebarSnapshot["spaces"] = [];
+  // Your servers render even when empty: a freshly created server must be
+  // visible and enterable immediately, not appear only once it has rooms.
+  for (const space of input.spaces) {
+    if (!space.joined) continue;
+    spaces.push({ space, rooms: bySpace.get(space.spaceId) ?? [] });
+    bySpace.delete(space.spaceId);
+  }
+  for (const [spaceId, spaceRooms] of bySpace) {
+    const space = knownSpaces.get(spaceId) ?? {
+      spaceId,
+      name: spaceId,
+      ownerUserId: "",
+      createdAt: "",
+    };
+    spaces.push({ space, rooms: spaceRooms });
+  }
+  // Discord-stable server order: creation time, never name. Names arrive
+  // late for spaces synthesized from room leftovers, and sorting by them
+  // made the rail reshuffle mid-session. Unknown createdAt sorts last,
+  // deterministically by id.
+  const createdKey = (space: RoomSpace): number => {
+    const at = new Date(space.createdAt).getTime();
+    return Number.isFinite(at) && at > 0 ? at : Number.MAX_SAFE_INTEGER;
+  };
+  spaces.sort(
+    (a, b) =>
+      createdKey(a.space) - createdKey(b.space) || a.space.spaceId.localeCompare(b.space.spaceId),
+  );
+
+  const popular = rooms
+    .filter((room) => !room.joined)
+    .sort((a, b) => b.heatScore - a.heatScore || b.online - a.online)
+    .slice(0, POPULAR_MAX);
+
+  return {
+    spaces,
+    unspaced,
+    dms: input.dms,
+    popular,
+    globalReplyUnread: Math.max(0, input.globalReplyUnread),
+    fetchedAt: input.now,
+  };
+}
+
+export interface SidebarModelDeps {
+  fetchRooms: () => Promise<RoomMeta[]>;
+  fetchSpaces: () => Promise<RoomSpace[]>;
+  fetchReadState: (roomNames: string[]) => Promise<Record<string, number>>;
+  fetchDms: () => Promise<SidebarDm[]>;
+  fetchGlobalReplyUnread: () => Promise<number>;
+  joinedUnread: (roomName: string) => number | null;
+  now?: () => number;
+}
+
+export class SidebarModel {
+  private snapshotValue: SidebarSnapshot = EMPTY_SIDEBAR_SNAPSHOT;
+  private inflight: Promise<SidebarSnapshot> | null = null;
+  private readonly listeners = new Set<() => void>();
+
+  constructor(private readonly deps: SidebarModelDeps) {}
+
+  snapshot(): SidebarSnapshot {
+    return this.snapshotValue;
+  }
+
+  onUpdate(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Post-mutation refresh: if a poll-triggered load is already in flight it
+   * may predate the caller's writes, so wait it out and load AGAIN. Readers
+   * keep using the coalescing refresh(); writers use this barrier.
+   */
+  async refreshAfterWrite(): Promise<SidebarSnapshot> {
+    if (this.inflight) await this.inflight.catch(() => undefined);
+    return this.refresh();
+  }
+
+  /** Single-flight refresh; failures keep the previous snapshot. */
+  refresh(): Promise<SidebarSnapshot> {
+    if (this.inflight) return this.inflight;
+    this.inflight = this.load()
+      .then((snapshot) => {
+        this.snapshotValue = snapshot;
+        for (const listener of this.listeners) listener();
+        return snapshot;
+      })
+      .catch(() => this.snapshotValue)
+      .finally(() => {
+        this.inflight = null;
+      }) as Promise<SidebarSnapshot>;
+    return this.inflight;
+  }
+
+  private async load(): Promise<SidebarSnapshot> {
+    const [rooms, spaces, dms, globalReplyUnread] = await Promise.all([
+      this.deps.fetchRooms(),
+      this.deps.fetchSpaces().catch(() => [] as RoomSpace[]),
+      this.deps.fetchDms().catch(() => [] as SidebarDm[]),
+      this.deps.fetchGlobalReplyUnread().catch(() => 0),
+    ]);
+    const readState = await this.deps
+      .fetchReadState(rooms.map((room) => room.name))
+      .catch(() => ({}) as Record<string, number>);
+    return buildSidebarSnapshot({
+      rooms,
+      spaces,
+      readState,
+      dms,
+      globalReplyUnread,
+      joinedUnread: this.deps.joinedUnread,
+      now: (this.deps.now ?? Date.now)(),
+    });
+  }
+}