@a-t-h-i/bot-lobby 0.6.7 → 0.6.9

package/src/classifier/instance.ts

@@ -11,6 +11,7 @@ import { isSubagentProcess } from "../pi/quiet.ts";
 import { Classifier } from "./classifier.ts";
 import { registerJevProvider, type KeySource, type KeyStatus } from "./hosts.ts";
 import { fileHinter, type FileHinter, type FileScope } from "./files.ts";
+import { knowledgePicker, type KnowledgePicker } from "./knowledge.ts";
 import { lobbyFeed } from "../lobby/feed.ts";
 import { triageLine, triageWithContext } from "./triage.ts";
 import type { TaskTriage } from "../schemas/task.ts";
@@ -45,6 +46,11 @@ export function hintsFor(scope: FileScope): FileHinter {
   return fileHinter(classifier(), scope, (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
 }
 
+/** Relevant knowledge for agents, with what Jev kept of each long file logged to the lobby's activity feed. */
+export function knowledgeFor(): KnowledgePicker {
+  return knowledgePicker(classifier(), (text) => lobbyFeed.log("CLASSIFIER", text, "info"));
+}
+
 /** Triage a request for a task in a tree, logged to the lobby's activity feed; undefined when triage is off or fails. */
 export async function triageFor(scope: FileScope, request: string, signal?: AbortSignal): Promise<TaskTriage | undefined> {
   const triage = await triageWithContext(classifier(), scope, request, signal);

package/src/classifier/knowledge.ts

@@ -0,0 +1,158 @@
+/**
+ * Relevant knowledge. An agent's knowledge, standards and decisions are put in
+ * its prompt, not looked up, so a gate ("does this step need the knowledge
+ * base?") would have to guess before the agent knows what it needs, and a wrong
+ * "no" is silent. What Jev does safely instead is the ranking the keyword
+ * selector does badly: when a file is longer than the prompt has room for, Jev
+ * judges each of its sections against the step (one yes/no per section) and the
+ * ones that bear on it stay. A file that fits goes in whole and costs nothing.
+ *
+ * Whatever is left out is said so, with the file's path, so an agent that does
+ * need it reads the rest itself. Any failure, timeout or switch-off keeps the
+ * keyword selection, which is what agents got before.
+ */
+import { basename } from "node:path";
+import { score, selectRelevant, splitSections, tokenize, type KnowledgeInput, type KnowledgeSelection } from "../knowledge/selector.ts";
+import type { Classifier } from "./classifier.ts";
+import { noul, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+
+/** How many characters of each knowledge file a prompt has room for. */
+export const KNOWLEDGE_BUDGET_CHARS = 4000;
+/** A section is judged on its first characters; the whole section is kept when it stays. */
+export const SECTION_EXCERPT_CHARS = 700;
+/** Sections judged per file; a longer file is narrowed by keywords first. */
+export const MAX_SECTIONS = 60;
+/** The step waits this long for Jev, then goes with keywords. */
+export const KNOWLEDGE_BUDGET_MS = 1500;
+
+/** The three files a prompt carries: `knowledge`, `standards` and `decisions`. */
+export type KnowledgeSlice = keyof KnowledgeSelection;
+export type KnowledgePaths = Partial<Record<KnowledgeSlice, string>>;
+
+export interface SectionCall {
+  request: SystemOneRequest;
+  /** The section each question key stands for, by index into the file's sections. */
+  keys: Map<string, number>;
+}
+
+/** One request that asks about each candidate section of a file. */
+export function sectionRequest(task: string, sections: readonly string[], candidates: readonly number[]): SectionCall {
+  const entries: Record<string, string> = {};
+  const questions: SystemOneRequest["questions"] = {};
+  const keys = new Map<string, number>();
+  candidates.forEach((index, position) => {
+    const key = `s${position + 1}`;
+    entries[key] = clip(sections[index]!, SECTION_EXCERPT_CHARS);
+    questions[key] = noul(`Does \`sections.${key}\` hold a fact, rule or decision that an agent doing \`task\` should have in front of it? Yes when it bears on the code, files, conventions or choices the task touches; no when it is about something else or only shares words with it.`);
+    keys.set(key, index);
+  });
+  return { request: { state: { task: clip(task, 3000), sections: entries }, questions }, keys };
+}
+
+/** The sections to judge: all of them, or the `MAX_SECTIONS` that share the most words with the task. */
+export function candidateSections(task: string, sections: readonly string[]): number[] {
+  const all = sections.map((_, index) => index);
+  if (sections.length <= MAX_SECTIONS) return all;
+  const tokens = tokenize(task);
+  const scored = all.map((index) => ({ index, hits: score(sections[index]!, tokens) }));
+  scored.sort((a, b) => b.hits - a.hits || b.index - a.index);
+  return scored.slice(0, MAX_SECTIONS).map((entry) => entry.index).sort((a, b) => a - b);
+}
+
+/** What was kept of a file: its text and how many of its sections that was. */
+export interface Kept {
+  text: string;
+  kept: number;
+  total: number;
+}
+
+/**
+ * The most relevant sections that fit `budget`, in the order of the file. A
+ * section too long to fit on its own is cut to fit when nothing else is kept.
+ */
+export function keepSections(sections: readonly string[], relevance: ReadonlyMap<number, number>, floor: number, budget: number): Kept {
+  const wanted = [...relevance].filter(([, value]) => value >= floor).sort((a, b) => b[1] - a[1] || a[0] - b[0]);
+  const chosen: number[] = [];
+  const texts = new Map<number, string>();
+  let used = 0;
+  for (const [index] of wanted) {
+    const text = sections[index]!;
+    if (used + text.length <= budget) {
+      chosen.push(index);
+      texts.set(index, text);
+      used += text.length + 2;
+    } else if (chosen.length === 0) {
+      chosen.push(index);
+      texts.set(index, clip(text, budget));
+      used = budget;
+    }
+  }
+  chosen.sort((a, b) => a - b);
+  return { text: chosen.map((index) => texts.get(index)!).join("\n\n").trim(), kept: chosen.length, total: sections.length };
+}
+
+/** The line that tells an agent what it was not given, and where all of it is. */
+export function leftOutNote(kept: Kept, name: string, path?: string): string {
+  const where = path ? ` The whole file is ${path}.` : "";
+  return kept.kept === 0
+    ? `_No section of ${name} bears on this step (${kept.total} sections).${where}_`
+    : `_Kept ${kept.kept} of ${kept.total} sections of ${name} for this step.${where}_`;
+}
+
+/** Picks what an agent's prompt carries of its knowledge files. */
+export interface KnowledgePicker {
+  select(task: string, files: KnowledgeInput, options?: { signal?: AbortSignal; paths?: KnowledgePaths }): Promise<KnowledgeSelection>;
+}
+
+const SLICES: readonly KnowledgeSlice[] = ["knowledge", "standards", "decisions"];
+
+/**
+ * Jev's picks for one file over the budget, or undefined when it cannot judge
+ * (off, failed, out of time, no key): the caller then uses keywords.
+ */
+async function rank(classifier: Classifier, task: string, content: string, budget: number, options: { signal?: AbortSignal }): Promise<{ kept: Kept; sections: string[]; ms: number } | undefined> {
+  const sections = splitSections(content.trim());
+  if (sections.length < 2) return undefined;
+  const call = sectionRequest(task, sections, candidateSections(task, sections));
+  const result = await classifier.ask("knowledge", call.request, { ...(options.signal ? { signal: options.signal } : {}), timeoutMs: Math.min(classifier.config.timeoutMs, KNOWLEDGE_BUDGET_MS) });
+  if (!result) return undefined;
+  const relevance = new Map<number, number>();
+  for (const [key, index] of call.keys) {
+    const value = yesOf(result.answers, key);
+    if (value !== undefined) relevance.set(index, value);
+  }
+  // An answer to none of the questions says nothing: keywords decide.
+  if (relevance.size === 0) return undefined;
+  return { kept: keepSections(sections, relevance, classifier.config.thresholds.knowledgeRelevantAt, budget), sections, ms: result.ms };
+}
+
+/**
+ * A picker on Jev. Files that fit the prompt are untouched; a longer one keeps
+ * the sections Jev judges to bear on the step, with a note of what was left
+ * out. Standards are the exception to an empty result: they are rules for all
+ * work, so when Jev sees none that applies the keyword selection stands.
+ */
+export function knowledgePicker(classifier: Classifier, log?: (text: string) => void, budget = KNOWLEDGE_BUDGET_CHARS): KnowledgePicker {
+  return {
+    async select(task, files, options = {}) {
+      const plain = (kind: KnowledgeSlice) => selectRelevant(task, files[kind] ?? "", budget);
+      const picked = await Promise.all(SLICES.map(async (kind): Promise<string> => {
+        const content = files[kind] ?? "";
+        if (content.trim().length <= budget || !task.trim() || !classifier.enabled("knowledge")) return plain(kind);
+        try {
+          const ranked = await rank(classifier, task, content, budget, options.signal ? { signal: options.signal } : {});
+          if (!ranked) return plain(kind);
+          const path = options.paths?.[kind];
+          const name = path ? basename(path) : kind;
+          if (ranked.kept.kept === 0 && kind === "standards") return plain(kind);
+          log?.(`knowledge: kept ${ranked.kept.kept} of ${ranked.kept.total} sections of ${name} · ${ranked.ms} ms`);
+          return [ranked.kept.text, leftOutNote(ranked.kept, name, path)].filter(Boolean).join("\n\n");
+        } catch {
+          return plain(kind);
+        }
+      }));
+      return { knowledge: picked[0]!, standards: picked[1]!, decisions: picked[2]! };
+    },
+  };
+}

package/src/classifier/review.ts

@@ -0,0 +1,146 @@
+/**
+ * Jev's quick read of a pull request, for the Git tab: how big the change is,
+ * how likely it is risky, to break callers, to touch security-sensitive code
+ * or to change behaviour without tests, and what kind of change it is — in
+ * one call, in a moment, without writing a word. It is a triage, not a review:
+ * it says whether a full review by an agent is worth its tokens.
+ */
+import type { Classifier } from "./classifier.ts";
+import { choice, choiceOf, noul, score, scoreOf, yesOf, type SystemOneRequest } from "./client.ts";
+import { clip } from "./limits.ts";
+import { TRIAGE_SIZES } from "./triage.ts";
+import type { TriageSize } from "../schemas/task.ts";
+
+const SIZE_LEVELS = [
+  "trivial: a one-line or mechanical change (a rename, a typo, a version bump)",
+  "small: a few files in one area, following an existing pattern",
+  "medium: several files or two areas, with some design decisions",
+  "large: a cross-cutting change, a new subsystem, a migration or an architecture change",
+];
+
+const KINDS: Record<string, string> = {
+  feature: "New capability or behaviour",
+  bugfix: "Existing behaviour was wrong and is fixed",
+  refactor: "Restructures code without changing behaviour",
+  tests: "Adds or fixes tests only",
+  docs: "Documentation only",
+  dependency: "Upgrades or changes dependencies",
+  chore: "Configuration, build, tooling or cleanup",
+};
+
+/** The pull request as Jev reads it. */
+export interface PullInput {
+  title: string;
+  body: string;
+  /** Changed files with their line counts, e.g. `src/a.ts (+12 −3)`. */
+  files: readonly string[];
+  diff: string;
+}
+
+/** What Jev made of a pull request. */
+export interface PullRead {
+  size: TriageSize;
+  sizeConfidence: number;
+  /** Probabilities of yes, 0 to 1. */
+  risky: number;
+  breaking: number;
+  security: number;
+  testsMissing: number;
+  kind?: string;
+  kindProbability?: number;
+  model: string;
+  ms: number;
+}
+
+/** Characters of diff sent: the rest is what the agent's review is for. */
+export const READ_DIFF_CHARS = 80_000;
+
+export function pullRequest(input: PullInput): SystemOneRequest {
+  return {
+    state: {
+      title: clip(input.title, 300),
+      description: clip(input.body, 3000),
+      changed_files: clip(input.files.join("\n"), 4000),
+      diff: clip(input.diff, READ_DIFF_CHARS),
+    },
+    questions: {
+      size: score("How big is the change in `diff`, judged by what it would take to review and verify?", SIZE_LEVELS),
+      risky: noul(
+        "Could merging `diff` break existing behaviour or cause harm: data loss, corrupted state, wrong results, concurrency bugs, performance cliffs, or an outage?",
+        "Yes: there is a plausible way this breaks something that works today.",
+        "No: it is low-risk, well contained, or purely additive.",
+      ),
+      breaking: noul(
+        "Does `diff` change a public API, a config or file format, a database schema or a command-line interface in a way that breaks existing callers or users?",
+        "Yes: something outside this change has to adapt.",
+        "No: existing callers and data keep working as they are.",
+      ),
+      security: noul(
+        "Does `diff` touch authentication, authorisation, secrets, input validation, cryptography, or other security-sensitive code?",
+        "Yes: a mistake here could be a vulnerability.",
+        "No: nothing in it is security-relevant.",
+      ),
+      tests_missing: noul(
+        "Does `diff` change behaviour without adding or updating tests that cover the change?",
+        "Yes: the behaviour changes and no test in the diff covers it.",
+        "No: it adds or updates tests for what it changes, or it changes no behaviour.",
+      ),
+      kind: choice("What kind of change is `diff`?", KINDS),
+    },
+  };
+}
+
+/** Jev's read of a pull request, or undefined when the classifier is off or fails. */
+export async function readPull(classifier: Classifier, input: PullInput, signal?: AbortSignal): Promise<PullRead | undefined> {
+  if (!classifier.enabled("review")) return undefined;
+  const result = await classifier.ask("review", pullRequest(input), signal ? { signal } : {});
+  if (!result) return undefined;
+  const size = scoreOf(result.answers, "size");
+  if (!size) return undefined;
+  const kind = choiceOf(result.answers, "kind");
+  return {
+    size: TRIAGE_SIZES[Math.max(0, Math.min(TRIAGE_SIZES.length - 1, size.level))]!,
+    sizeConfidence: size.confidence,
+    risky: yesOf(result.answers, "risky") ?? 0,
+    breaking: yesOf(result.answers, "breaking") ?? 0,
+    security: yesOf(result.answers, "security") ?? 0,
+    testsMissing: yesOf(result.answers, "tests_missing") ?? 0,
+    ...(kind ? { kind: kind.choice, kindProbability: kind.probability } : {}),
+    model: result.model,
+    ms: result.ms,
+  };
+}
+
+const CONCERN = 0.5;
+
+/** The concerns worth a look, most likely first, as words. */
+export function concerns(read: PullRead): string[] {
+  const found: Array<[number, string]> = [
+    [read.risky, "risky"],
+    [read.security, "touches security"],
+    [read.breaking, "may break callers"],
+    [read.testsMissing, "no tests for the change"],
+  ];
+  return found.filter(([probability]) => probability >= CONCERN).sort((a, b) => b[0] - a[0]).map(([, words]) => words);
+}
+
+/** Whether a full review by an agent is worth its tokens: a concern, or a change too big to skim. */
+export function worthReview(read: PullRead): boolean {
+  return concerns(read).length > 0 || read.size === "large";
+}
+
+/** One line: `medium · bugfix · risky 0.71, no tests for the change 0.64 → worth a full review`. */
+export function readLine(read: PullRead): string {
+  const kind = read.kind ? ` · ${read.kind}` : "";
+  const flagged = concerns(read);
+  const figures = [
+    ["risky", read.risky],
+    ["security", read.security],
+    ["breaking", read.breaking],
+    ["tests missing", read.testsMissing],
+  ] as const;
+  const detail = flagged.length > 0
+    ? figures.filter(([, probability]) => probability >= CONCERN).sort((a, b) => b[1] - a[1]).map(([name, probability]) => `${name} ${probability.toFixed(2)}`).join(", ")
+    : "nothing stands out";
+  return `${read.size}${kind} · ${detail} → ${worthReview(read) ? "worth a full review" : "looks routine"}`;
+}

package/src/excalidraw/check.ts

@@ -0,0 +1,31 @@
+/**
+ * "Does this session work?": join the room for a moment, as a seat named
+ * after the lobby, and say what is there — the server reached, who is in the
+ * room, how much is on the board, whether the link's key fits. The seat leaves
+ * again at once, so a check never leaves an extra collaborator in the room.
+ */
+import { ExcalidrawRoom, type RoomOptions } from "./client.ts";
+import { parseRoomLink } from "./room.ts";
+
+export interface CheckResult {
+  ok: boolean;
+  text: string;
+}
+
+export async function checkSession(link: string, name: string, options: Pick<RoomOptions, "server" | "sceneWaitMs" | "connectTimeoutMs" | "connect"> = {}): Promise<CheckResult> {
+  const parsed = parseRoomLink(link);
+  if (!parsed) return { ok: false, text: "not a valid room link" };
+  const room = new ExcalidrawRoom({ link: parsed, username: "bot-lobby · check", name, ...options });
+  try {
+    const status = await room.ready();
+    // Give an answer to the newcomer's arrival a moment more when someone is there but the board has not come yet.
+    if (status.undecryptable > 0 && status.elements === 0) return { ok: false, text: "reached the room, but its messages would not open: the link's key does not match, so it may have been copied incompletely" };
+    if (status.peers === 0) return { ok: true, text: "reached the server; nobody has this session open yet — open the link in Excalidraw, and agents can read and draw" };
+    const who = status.people.length > 0 ? status.people.join(", ") : `${status.peers} other${status.peers === 1 ? "" : "s"}`;
+    return { ok: true, text: `reached the room with ${who}; ${status.synced ? `${status.elements} element${status.elements === 1 ? "" : "s"} on the board` : "the board has not been sent yet (it comes when someone in the room answers)"}` };
+  } catch (error) {
+    return { ok: false, text: (error as Error).message };
+  } finally {
+    room.close();
+  }
+}

package/src/excalidraw/client.ts

@@ -0,0 +1,266 @@
+/**
+ * One agent's seat in an Excalidraw shared session. It joins the room the way
+ * a second browser tab would: over Excalidraw's collaboration socket, sending
+ * and receiving the encrypted scene messages every client in the room sends.
+ * Others in the room answer a newcomer with the whole scene, so a seat learns
+ * the board from whoever is there; what the agent draws goes out as an update
+ * that every browser merges in place, under the agent's name.
+ *
+ * A seat never answers a newcomer with a scene it does not have: a browser
+ * that took an empty scene from an agent would skip loading the board it saved
+ * itself. And it does not draw while nobody else is in the room, because
+ * nothing keeps a scene for a room but the browsers in it.
+ */
+import { io, type Socket } from "socket.io-client";
+import { DEFAULT_SERVER, seal, unseal, type RoomLink } from "./room.ts";
+import { describeScene, mergeElements, plainText, planDraw, sceneBounds, visible, type DrawOutcome, type DrawRequest, type Scene, type SceneElement } from "./scene.ts";
+
+/** The part of a socket.io client a seat uses; tests and other transports can stand in for it. */
+export type SocketLike = Pick<Socket, "on" | "emit" | "close" | "connected"> & { id?: string | undefined };
+
+export interface RoomOptions {
+  link: Pick<RoomLink, "roomId" | "roomKey">;
+  /** The name other people see next to this seat's cursor. */
+  username: string;
+  /** The session's name in the lobby, for readings and messages. */
+  name: string;
+  server?: string;
+  connect?: (server: string) => SocketLike;
+  /** Give up on reaching the server after this long. */
+  connectTimeoutMs?: number;
+  /** How long to wait for a collaborator to send the scene (Excalidraw's own client waits five seconds). */
+  sceneWaitMs?: number;
+}
+
+export interface RoomStatus {
+  connected: boolean;
+  /** Others in the room, people and agents, not counting this seat. */
+  peers: number;
+  /** A collaborator has sent the whole scene. */
+  synced: boolean;
+  elements: number;
+  /** Messages that would not open: the link's key does not match the room's. */
+  undecryptable: number;
+  /** Names the collaborators have given themselves. */
+  people: string[];
+}
+
+const CONNECT_TIMEOUT_MS = 10_000;
+const SCENE_WAIT_MS = 5000;
+/** The collaboration server relays at most a megabyte a message; a scene near that is not sent whole. */
+const MAX_MESSAGE_CHARS = 900_000;
+
+function defaultConnect(server: string): SocketLike {
+  return io(server, { transports: ["websocket", "polling"], autoUnref: true, timeout: 8000 });
+}
+
+export function collaborationServer(env: NodeJS.ProcessEnv = process.env): string {
+  return env.BOT_LOBBY_EXCALIDRAW_SERVER?.trim() || DEFAULT_SERVER;
+}
+
+export class ExcalidrawRoom {
+  readonly scene: Scene = new Map();
+  private readonly options: RoomOptions;
+  private socket: SocketLike | undefined;
+  private opening: Promise<RoomStatus> | undefined;
+  private peerIds: string[] = [];
+  private readonly names = new Map<string, string>();
+  private synced = false;
+  private undecryptable = 0;
+  private closed = false;
+  private timers: Array<ReturnType<typeof setTimeout>> = [];
+
+  constructor(options: RoomOptions) {
+    this.options = options;
+  }
+
+  get name(): string {
+    return this.options.name;
+  }
+
+  /** Which room this seat is in; a seat is replaced when its session's link changes. */
+  get linkKey(): string {
+    return `${this.options.link.roomId},${this.options.link.roomKey}`;
+  }
+
+  status(): RoomStatus {
+    return {
+      connected: this.socket?.connected ?? false,
+      peers: this.peerIds.length,
+      synced: this.synced,
+      elements: visible(this.scene).length,
+      undecryptable: this.undecryptable,
+      people: [...new Set(this.peerIds.map((id) => this.names.get(id)).filter((name): name is string => Boolean(name)))],
+    };
+  }
+
+  /** Join the room (once) and wait until a collaborator has sent the scene, or the wait for it is over. */
+  ready(): Promise<RoomStatus> {
+    this.opening ??= this.open();
+    return this.opening;
+  }
+
+  private open(): Promise<RoomStatus> {
+    return new Promise((resolve, reject) => {
+      // A seat that failed to connect once may try again.
+      this.closed = false;
+      const { roomId } = this.options.link;
+      const server = this.options.server ?? collaborationServer();
+      const socket = (this.options.connect ?? defaultConnect)(server);
+      this.socket = socket;
+      let done = false;
+      let lastError = "";
+      const settle = () => {
+        if (done) return;
+        done = true;
+        resolve(this.status());
+        this.announce();
+      };
+      this.timers.push(
+        setTimeout(() => {
+          if (done) return;
+          done = true;
+          this.opening = undefined;
+          this.close();
+          reject(new Error(`could not reach the Excalidraw collaboration server ${server}${lastError ? ` (${lastError})` : ""}`));
+        }, this.options.connectTimeoutMs ?? CONNECT_TIMEOUT_MS),
+      );
+      socket.on("connect_error", (error: Error) => {
+        lastError = error.message;
+      });
+      // Every (re)connection is greeted with init-room; the seat answers by joining.
+      socket.on("init-room", () => {
+        socket.emit("join-room", roomId);
+        this.timers.push(setTimeout(settle, this.options.sceneWaitMs ?? SCENE_WAIT_MS));
+      });
+      socket.on("first-in-room", () => settle());
+      socket.on("room-user-change", (clients: string[]) => {
+        this.peerIds = clients.filter((id) => id !== socket.id);
+        for (const id of [...this.names.keys()]) if (!clients.includes(id)) this.names.delete(id);
+      });
+      socket.on("new-user", () => {
+        // What this seat does not know, it does not claim to.
+        if (this.synced || visible(this.scene).length > 0) void this.send("SCENE_INIT", [...this.scene.values()]);
+      });
+      socket.on("client-broadcast", (data: unknown, iv: unknown) => {
+        void this.receive(data, iv).then((initial) => {
+          if (initial) settle();
+        });
+      });
+    });
+  }
+
+  /** A received message; true when it was the scene a newcomer is waiting for. */
+  private async receive(data: unknown, iv: unknown): Promise<boolean> {
+    const message = (await unseal(this.options.link.roomKey, data, iv)) as { type?: string; payload?: Record<string, unknown> } | undefined;
+    if (!message || typeof message !== "object") {
+      this.undecryptable += 1;
+      return false;
+    }
+    const payload = message.payload ?? {};
+    switch (message.type) {
+      case "SCENE_INIT":
+      case "SCENE_UPDATE":
+        if (Array.isArray(payload.elements)) mergeElements(this.scene, payload.elements);
+        if (message.type === "SCENE_INIT") this.synced = true;
+        return message.type === "SCENE_INIT";
+      case "MOUSE_LOCATION":
+      case "IDLE_STATUS":
+        if (typeof payload.socketId === "string" && typeof payload.username === "string" && plainText(payload.username)) this.names.set(payload.socketId, plainText(payload.username).slice(0, 40));
+        return false;
+      default:
+        return false;
+    }
+  }
+
+  /** Send a scene message to the room; false when the seat is not connected. */
+  private async send(type: "SCENE_INIT" | "SCENE_UPDATE" | "IDLE_STATUS" | "MOUSE_LOCATION", body: unknown): Promise<boolean> {
+    const socket = this.socket;
+    if (!socket?.connected || this.closed) return false;
+    const payload = type === "SCENE_INIT" || type === "SCENE_UPDATE" ? { elements: body } : body;
+    if (JSON.stringify(payload).length > MAX_MESSAGE_CHARS) return false;
+    const sealed = await seal(this.options.link.roomKey, { type, payload });
+    socket.emit("server-broadcast", this.options.link.roomId, sealed.data, sealed.iv);
+    return true;
+  }
+
+  /**
+   * Tell the room who this seat is (its collaborator name), and where it just
+   * drew. Excalidraw sends these as volatile messages because it sends them
+   * constantly; a seat says it once, so it does not let the server drop it.
+   */
+  private announce(near?: { x: number; y: number }): void {
+    const socketId = this.socket?.id;
+    if (!socketId) return;
+    void this.send("IDLE_STATUS", { socketId, userState: "active", username: this.options.username });
+    if (near) void this.send("MOUSE_LOCATION", { socketId, pointer: { x: near.x, y: near.y, tool: "pointer" }, button: "up", selectedElementIds: {}, username: this.options.username });
+  }
+
+  /** Why nothing may be drawn right now, or undefined when it may. */
+  cannotDraw(): string | undefined {
+    if (!this.socket?.connected) return "this seat is not connected to the room";
+    if (this.peerIds.length === 0) return "nobody else is in the room, and only a browser keeps a room's board; ask the user to open the session's link in Excalidraw, then try again";
+    return undefined;
+  }
+
+  /** Draw: the elements go out to the room and into this seat's own scene. */
+  async draw(request: DrawRequest): Promise<DrawOutcome> {
+    const outcome = planDraw(this.scene, request);
+    if (outcome.changed.length === 0) return outcome;
+    const reason = this.cannotDraw();
+    if (reason) return { ...outcome, changed: [], drawn: [], removed: [], problems: [...outcome.problems, reason] };
+    for (const element of outcome.changed) this.scene.set(element.id, element);
+    await this.send("SCENE_UPDATE", outcome.changed);
+    const around = sceneBounds(outcome.changed.filter((element) => !element.isDeleted));
+    this.announce(around ? { x: around.x1, y: around.y1 } : undefined);
+    return outcome;
+  }
+
+  /** The board in words, for a model, with what is known about the room around it. */
+  read(): string {
+    const status = this.status();
+    const notes: string[] = [];
+    if (!status.connected) notes.push("Not connected to the room right now; this is the board as last seen.");
+    else if (status.undecryptable > 0 && status.elements === 0) notes.push("Messages in this room would not open: the session link's key does not match the room's, so it may have been copied incompletely.");
+    else if (status.peers === 0) notes.push("Nobody else is in the room, so the board above is not known: ask the user to open the session's link in Excalidraw, then read again.");
+    else if (!status.synced) notes.push("No collaborator has sent the whole board yet, so this may be incomplete; read again in a few seconds.");
+    if (status.peers > 0) notes.push(`In the room with you: ${status.people.length > 0 ? status.people.join(", ") : `${status.peers} other${status.peers === 1 ? "" : "s"}`}.`);
+    return [describeScene(this.scene, this.options.name), ...notes].join("\n");
+  }
+
+  elements(): SceneElement[] {
+    return visible(this.scene);
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const timer of this.timers) clearTimeout(timer);
+    this.timers = [];
+    this.socket?.close();
+  }
+}
+
+/** The seats an agent has open, one per session, kept for the length of its run. */
+export class RoomPool {
+  private readonly rooms = new Map<string, ExcalidrawRoom>();
+  private readonly make: (options: RoomOptions) => ExcalidrawRoom;
+
+  constructor(make: (options: RoomOptions) => ExcalidrawRoom = (options) => new ExcalidrawRoom(options)) {
+    this.make = make;
+  }
+
+  /** The seat for a session, opened on first use; a session whose link changed gets a new seat. */
+  room(key: string, options: RoomOptions): ExcalidrawRoom {
+    const existing = this.rooms.get(key);
+    if (existing && existing.linkKey === `${options.link.roomId},${options.link.roomKey}`) return existing;
+    existing?.close();
+    const room = this.make(options);
+    this.rooms.set(key, room);
+    return room;
+  }
+
+  closeAll(): void {
+    for (const room of this.rooms.values()) room.close();
+    this.rooms.clear();
+  }
+}