pi-roundtable-web 0.25.0 → 0.26.1

package/src/app/sockets.ts

@@ -1,32 +1,79 @@
-import type { ActorFacts, Logger, RouteSocket } from "pi-roundtable";
+import type { ActorFacts, Logger, RouteSocket, Tier } from "pi-roundtable";
 import type { ServerFrame } from "../api-types.ts";
 
-/** One open WebSocket of an owner: who, what the page shows, and when its credential lapses. */
+/** One open WebSocket: who, what the page shows, and when its credential lapses. */
 export interface AppSocket {
 	principal: { id: string; name: string };
 	/** The actor the credential vouched for, which the person's messages are written as. */
 	actor: ActorFacts | undefined;
 	expiresAt: Date | undefined;
+	/** The tier they hold, as of the upgrade or the latest frame or recheck. */
+	tier: Tier;
+	/** The identity they spoke as; the principal's id when the credential names none. */
+	speakerId: string;
+	/** The roles their sign-in carried. */
+	roles: readonly string[];
+	/** A required onboarding step stands undone: only the frames a gated socket may have reach it. */
+	gated: boolean;
+	/** The session the socket came in on, for the recheck that asks whether it still stands. */
+	session?: string | undefined;
 	/** The page is in view; a push goes out only when no socket is. */
 	visible: boolean;
 	/** The room the page shows, whose progress streams to it. */
 	focus: string | undefined;
+	/** The host rooms the socket follows. */
+	subscriptions: Set<string>;
+	/** Set once `ready` and the replay went out: until then nothing but a frame addressed to the socket reaches it. */
+	started?: boolean;
 	socket?: RouteSocket<AppSocket>;
 	/** Closes the socket when its credential lapses or the cap on its life is reached. */
 	expiry?: ReturnType<typeof setTimeout>;
-	/** Looks again at whether the person is still an owner. */
+	/** Looks again at whether the person is still admitted, and at which tier. */
 	recheck?: ReturnType<typeof setInterval>;
 }
 
-/** The open sockets. Every one belongs to an owner, so a frame for the owners goes to them all. */
+/**
+ * Who a frame is for. There is no unaddressed send: every frame names its audience, and the
+ * open-time replay goes through the same filter as a live frame.
+ */
+export type Audience =
+	/** Sockets whose tier is owner now; with `focus`, those showing that room. */
+	| { owners: true; focus?: string }
+	/** Every socket of one person. */
+	| { principal: string }
+	/** The sockets that follow a host room and may read it now; with `focus`, those also showing it. */
+	| { room: string; focus?: true }
+	/** One socket; with `audience`, only if it is also in that audience (the replay on open). */
+	| { connection: AppSocket; audience?: Audience };
+
+/** The frames a gated socket still gets: the gate itself, the person's notices and badge, and refusals. */
+const GATED_FRAMES: ReadonlySet<ServerFrame["type"]> = new Set([
+	"ready",
+	"refused",
+	"gate",
+	"notice",
+	"notice_resolved",
+	"badge",
+]);
+
+/** Whether a socket may read a host room now; answered from a memo, so it costs no lookup. */
+export type RoomReader = (connection: AppSocket, room: string) => boolean;
+
+/** The open sockets, and the one way to put a frame on them. */
 export class Sockets {
 	readonly #open = new Set<AppSocket>();
 	readonly #logger: Logger;
+	#reader: RoomReader = () => false;
 
 	constructor(logger: Logger) {
 		this.#logger = logger;
 	}
 
+	/** Sets who may read which host room; until it is set, no host room frame reaches anyone. */
+	setRoomReader(reader: RoomReader): void {
+		this.#reader = reader;
+	}
+
 	add(connection: AppSocket, socket: RouteSocket<AppSocket>): void {
 		connection.socket = socket;
 		this.#open.add(connection);
@@ -40,8 +87,42 @@ export class Sockets {
 		this.#open.delete(connection);
 	}
 
-	/** Sends a frame on one socket; a dropped send is logged, never thrown. */
-	send(connection: AppSocket, frame: ServerFrame): void {
+	/** Whether the connection is in the audience now. */
+	reaches(connection: AppSocket, audience: Audience): boolean {
+		if ("connection" in audience)
+			return (
+				audience.connection === connection &&
+				(!audience.audience || this.reaches(connection, audience.audience))
+			);
+		if (!connection.started) return false;
+		if ("owners" in audience)
+			return (
+				connection.tier === "owner" &&
+				(audience.focus === undefined || connection.focus === audience.focus)
+			);
+		if ("principal" in audience)
+			return connection.principal.id === audience.principal;
+		return (
+			connection.subscriptions.has(audience.room) &&
+			this.#reader(connection, audience.room) &&
+			(!audience.focus || connection.focus === audience.room)
+		);
+	}
+
+	/**
+	 * Puts a frame on the sockets in `audience`, except `except`. A gated socket gets only what the
+	 * gate lets through. A dropped send is logged, never thrown.
+	 */
+	deliver(frame: ServerFrame, audience: Audience, except?: AppSocket): void {
+		for (const connection of this.#open) {
+			if (connection === except || !this.reaches(connection, audience))
+				continue;
+			if (connection.gated && !GATED_FRAMES.has(frame.type)) continue;
+			this.#send(connection, frame);
+		}
+	}
+
+	#send(connection: AppSocket, frame: ServerFrame): void {
 		const result = connection.socket?.send(JSON.stringify(frame));
 		if (result === "dropped")
 			this.#logger.warn(
@@ -50,18 +131,7 @@ export class Sockets {
 			);
 	}
 
-	/** Sends a frame to every open socket, or those `where` accepts, except `except`. */
-	broadcast(
-		frame: ServerFrame,
-		where?: (connection: AppSocket) => boolean,
-		except?: AppSocket,
-	): void {
-		for (const connection of this.#open)
-			if (connection !== except && (!where || where(connection)))
-				this.send(connection, frame);
-	}
-
-	/** Whether a page of this person is in view now; of any owner when no one is named. */
+	/** Whether a page of this person is in view now; of any person when none is named. */
 	anyVisible(principalId?: string): boolean {
 		for (const connection of this.#open)
 			if (
@@ -72,10 +142,28 @@ export class Sockets {
 		return false;
 	}
 
+	/** Calls `visit` on each open socket `where` accepts. */
+	each(
+		where: (connection: AppSocket) => boolean,
+		visit: (connection: AppSocket) => void,
+	): void {
+		for (const connection of [...this.#open])
+			if (where(connection)) visit(connection);
+	}
+
+	/** Closes the sockets `where` accepts, such as those of a session that ended. */
+	closeWhere(
+		where: (connection: AppSocket) => boolean,
+		code: number,
+		reason: string,
+	): void {
+		for (const connection of [...this.#open])
+			if (where(connection)) connection.socket?.close(code, reason);
+	}
+
 	/** Closes every socket, when the app stops. */
 	closeAll(code: number, reason: string): void {
-		for (const connection of [...this.#open])
-			connection.socket?.close(code, reason);
+		this.closeWhere(() => true, code, reason);
 	}
 
 	get size(): number {

package/src/app/surface.ts

@@ -16,9 +16,9 @@ import {
 } from "pi-roundtable";
 import type { RoomFile, RoomMessage } from "../api-types.ts";
 import type { OwnerDesk } from "./desk.ts";
-import { type FileDir, typeByName } from "./files.ts";
+import { type FileBinding, type FileDir, typeByName } from "./files.ts";
 import type { NewRoomMessage, RoomLog } from "./room-log.ts";
-import type { AppSocket, Sockets } from "./sockets.ts";
+import type { AppSocket, Audience, Sockets } from "./sockets.ts";
 import { AppSurfaceThreads } from "./surface-threads.ts";
 import type { WebThreads } from "./threads.ts";
 import type { Uploads } from "./uploads.ts";
@@ -45,6 +45,12 @@ export interface AppSurfaceOptions {
 	threads: Pick<WebThreads, "open" | "close">;
 	/** Whether a room can host a thread: an agent's or group's room that exists. */
 	canHost(parent: ChannelKey): Promise<boolean>;
+	/** Who has a room's frames: the owners' sockets for an agent room, a host room's readers for a host room. */
+	audienceOf(room: string): Audience;
+	/** Whether the room is a host's (its frames are the `host_*` ones). */
+	isHostRoom(room: string): boolean;
+	/** What binds a file an agent attaches in a host room, so its readers are served it. */
+	fileBinding?(room: string): FileBinding | undefined;
 	/** Tells the sockets the room list differs, once changes settle. */
 	changed(): void;
 	/**
@@ -54,6 +60,8 @@ export interface AppSurfaceOptions {
 	unprompted?(room: ChannelKey, author: string, text: string): void;
 	/** Called when a room's activity changes, so the presence table can follow. */
 	activity?(): void;
+	/** What was said in a host room since the assistant last posted; the host rooms' reader. */
+	channelContext?: ChatSurface["channelContext"];
 	/** The clock, in milliseconds; default `Date.now`. */
 	now?: () => number;
 	logger: Logger;
@@ -88,8 +96,8 @@ export interface RoomActivity {
 }
 
 /**
- * The owner app's rooms as a chat surface: what the host shows in a room reaches every socket of
- * every owner as a frame, and what a room says is stored in the room log. The agent team runs
+ * The owner app's rooms as a chat surface: what the host shows in a room reaches the sockets that
+ * may have it (the owners' for an agent room) as a frame, and what a room says is stored in the room log. The agent team runs
  * in the rooms (`agentRooms`) as it runs in its Discord channels, but each room is a
  * conversation of its own. A reply arrives whole, in Markdown, with its files stored, and an
  * agent's interim text is shown live until the final reply replaces it.
@@ -101,6 +109,8 @@ export class AppSurface implements ChatSurface {
 	readonly formatting = APP_FORMATTING;
 	/** The turn takes an upload up to the most the app lets a person upload. */
 	readonly maxAttachmentBytes: number;
+	/** Present on a surface with host rooms: what was said in one since the assistant last posted. */
+	channelContext?: ChatSurface["channelContext"];
 	readonly threads: AppSurfaceThreads;
 	readonly #options: AppSurfaceOptions;
 	readonly #activity = new Map<ChannelKey, Activity>();
@@ -114,6 +124,7 @@ export class AppSurface implements ChatSurface {
 		this.surface = options.surface;
 		this.maxAttachmentBytes = options.uploads.maxBytes;
 		this.#options = options;
+		if (options.channelContext) this.channelContext = options.channelContext;
 		this.threads = new AppSurfaceThreads({
 			surface: options.surface,
 			threads: options.threads,
@@ -147,26 +158,29 @@ export class AppSurface implements ChatSurface {
 		return this.#deliver !== undefined;
 	}
 
-	/** Stores a message of a room and shows it to every open socket, except `except`. */
+	/** Stores a message of a room and shows it to the sockets that may have the room, except `except`. */
 	async publish(row: NewRoomMessage, except?: AppSocket): Promise<RoomMessage> {
 		const message = await this.#options.log.append(row);
-		this.#options.sockets.broadcast(
-			{ type: "message", room: row.room, message },
-			undefined,
+		this.#options.sockets.deliver(
+			this.#options.isHostRoom(row.room)
+				? { type: "host_message", room: row.room, message }
+				: { type: "message", room: row.room, message },
+			this.#options.audienceOf(row.room),
 			except,
 		);
 		return message;
 	}
 
-	/** Changes the text of a stored message and shows the change to every open socket. */
+	/** Changes the text of a stored message and shows the change to the sockets that may have the room. */
 	async edit(room: ChannelKey, id: number, text: string): Promise<void> {
 		const message = await this.#options.log.edit(room, id, text);
 		if (!message) return;
-		this.#options.sockets.broadcast({
-			type: "edited",
-			room: message.room,
-			message,
-		});
+		this.#options.sockets.deliver(
+			this.#options.isHostRoom(room)
+				? { type: "host_edited", room: message.room, message }
+				: { type: "edited", room: message.room, message },
+			this.#options.audienceOf(room),
+		);
 	}
 
 	/** Whether a turn works in the room and whether Stop applies, as `activity` frames say. */
@@ -225,12 +239,15 @@ export class AppSurface implements ChatSurface {
 	}
 
 	#announce(room: ChannelKey, outcome?: "done" | "failed"): void {
-		this.#options.sockets.broadcast({
-			type: "activity",
-			room,
-			...this.activityOf(room),
-			...(outcome ? { outcome } : {}),
-		});
+		this.#options.sockets.deliver(
+			{
+				type: "activity",
+				room,
+				...this.activityOf(room),
+				...(outcome ? { outcome } : {}),
+			},
+			this.#options.audienceOf(room),
+		);
 		this.#options.activity?.();
 	}
 
@@ -283,7 +300,15 @@ export class AppSurface implements ChatSurface {
 		const entry = this.#activity.get(channel);
 		if (entry) entry.outcome = reply.failed ? "failed" : "done";
 		const files: RoomFile[] = (reply.files ?? []).map((file) =>
-			this.#options.files.put(file.name, typeByName(file.name), file.data),
+			this.#options.files.put(
+				file.name,
+				typeByName(file.name),
+				file.data,
+				undefined,
+				this.#options.isHostRoom(channel)
+					? this.#options.fileBinding?.(channel)
+					: undefined,
+			),
 		);
 		await this.publish({
 			room: channel,
@@ -328,21 +353,26 @@ export class AppSurface implements ChatSurface {
 				this.#speaks(channel, as?.agent);
 				const live = crypto.randomUUID();
 				const show = (current: string) =>
-					this.#options.sockets.broadcast({
-						type: "message",
-						room: channel,
-						message: {
-							id: 0,
+					this.#options.sockets.deliver(
+						{
+							type: this.#options.isHostRoom(channel)
+								? "host_message"
+								: "message",
 							room: channel,
-							kind: "agent",
-							...(as?.agent ? { agent: as.agent } : {}),
-							author: as?.name ?? ASSISTANT,
-							text: current,
-							files: [],
-							at: new Date().toISOString(),
-							live,
+							message: {
+								id: 0,
+								room: channel,
+								kind: "agent",
+								...(as?.agent ? { agent: as.agent } : {}),
+								author: as?.name ?? ASSISTANT,
+								text: current,
+								files: [],
+								at: new Date().toISOString(),
+								live,
+							},
 						},
-					});
+						this.#options.audienceOf(channel),
+					);
 				show(text);
 				return {
 					edit: async (edited) => {
@@ -362,9 +392,15 @@ export class AppSurface implements ChatSurface {
 
 	progress(channel: ChannelKey, event: TurnProgress): void {
 		this.#toolEvent(channel, event);
-		this.#options.sockets.broadcast(
+		// Only the sockets showing the room get its progress, and only those that may have the room.
+		const audience = this.#options.audienceOf(channel);
+		this.#options.sockets.deliver(
 			{ type: "progress", room: channel, event },
-			(connection) => connection.focus === channel,
+			"owners" in audience
+				? { owners: true, focus: channel }
+				: "room" in audience
+					? { room: audience.room, focus: true }
+					: audience,
 		);
 	}
 

package/src/app/threads.ts

@@ -60,6 +60,15 @@ export class WebThreads {
 		},
 	};
 
+	/** The mark of a finished thread the owners took off the room list; the thread itself stays. */
+	static readonly dismissedMigration: Migration = {
+		name: "web-threads-dismissed",
+		up: async (sql) => {
+			await sql`
+				ALTER TABLE web_threads ADD COLUMN IF NOT EXISTS dismissed_at timestamptz`;
+		},
+	};
+
 	/** Starts a thread under `parent`. */
 	async open(parent: string, title: string): Promise<WebThread> {
 		const id = `thread.${crypto.randomUUID()}`;
@@ -76,6 +85,26 @@ export class WebThreads {
 		await this.#sql`UPDATE web_threads SET open = false WHERE id = ${id}`;
 	}
 
+	/**
+	 * Takes a finished thread off the room list. It stays readable by its address, and asking again
+	 * changes nothing. An open thread is refused: `open` says so, `missing` that there is none.
+	 */
+	async dismiss(id: string): Promise<"dismissed" | "open" | "missing"> {
+		const rows: unknown[] = await this.#sql`
+			UPDATE web_threads SET dismissed_at = COALESCE(dismissed_at, now())
+			WHERE id = ${id} AND NOT open RETURNING 1`;
+		if (rows.length) return "dismissed";
+		return (await this.get(id)) ? "open" : "missing";
+	}
+
+	/** Dismisses every finished thread under `parent` that is still listed; returns how many. */
+	async dismissFinished(parent: string): Promise<number> {
+		const rows: unknown[] = await this.#sql`
+			UPDATE web_threads SET dismissed_at = now()
+			WHERE parent = ${parent} AND NOT open AND dismissed_at IS NULL RETURNING 1`;
+		return rows.length;
+	}
+
 	async get(id: string): Promise<WebThread | undefined> {
 		const [row]: Row[] = await this
 			.#sql`SELECT * FROM web_threads WHERE id = ${id}`;
@@ -98,14 +127,14 @@ export class WebThreads {
 
 	/**
 	 * The threads the room list shows, newest first: every open one, and the `closedLimit` newest
-	 * closed ones, which stay readable but are not kept in view for ever.
+	 * closed ones that were not dismissed. The rest stay readable but are not kept in view.
 	 */
 	async list(closedLimit = CLOSED_LISTED): Promise<WebThread[]> {
 		const rows: Row[] = await this.#sql`
 			SELECT * FROM (
 				SELECT * FROM web_threads WHERE open
 				UNION ALL
-				(SELECT * FROM web_threads WHERE NOT open
+				(SELECT * FROM web_threads WHERE NOT open AND dismissed_at IS NULL
 					ORDER BY created_at DESC, id LIMIT ${closedLimit})
 			) shown ORDER BY created_at DESC, id`;
 		return rows.map(threadOf);

package/src/app/uploads.ts

@@ -1,7 +1,12 @@
 import { extname } from "node:path";
 import type { AttachmentFile, AttachmentRef } from "pi-roundtable";
 import type { RoomFile, UploadView } from "../api-types.ts";
-import { FILE_RETENTION_MS, type FileDir, safeName } from "./files.ts";
+import {
+	FILE_RETENTION_MS,
+	type FileBinding,
+	type FileDir,
+	safeName,
+} from "./files.ts";
 import {
 	boundaryOf,
 	MultipartError,
@@ -32,7 +37,7 @@ const startsWith = (bytes: Uint8Array, signature: readonly number[], at = 0) =>
 const ascii = (text: string) => [...text].map((char) => char.charCodeAt(0));
 
 /** The image type the first bytes say, if any; these four are the ones the page shows itself. */
-function imageTypeOf(head: Uint8Array): string | undefined {
+export function imageTypeOf(head: Uint8Array): string | undefined {
 	if (startsWith(head, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
 		return "image/png";
 	if (startsWith(head, [0xff, 0xd8, 0xff])) return "image/jpeg";
@@ -153,6 +158,8 @@ export class Uploads {
 	readonly #now: () => number;
 	readonly maxBytes: number;
 	readonly #pendingBytes: number;
+	/** How long a stored file of an agent room is kept, in milliseconds. */
+	readonly #keepMs: number;
 
 	constructor(
 		waiting: FileDir,
@@ -161,6 +168,8 @@ export class Uploads {
 			maxBytes?: number;
 			/** The most bytes one person may have waiting; default 400 MiB. */
 			pendingBytes?: number;
+			/** How many days a stored file of an agent room is kept; default 30. */
+			keepDays?: number;
 			now?: () => number;
 		} = {},
 	) {
@@ -169,6 +178,10 @@ export class Uploads {
 		this.#now = options.now ?? Date.now;
 		this.maxBytes = options.maxBytes ?? DEFAULT_UPLOAD_MAX_BYTES;
 		this.#pendingBytes = options.pendingBytes ?? PENDING_BYTES_PER_PRINCIPAL;
+		this.#keepMs =
+			options.keepDays === undefined
+				? FILE_RETENTION_MS
+				: options.keepDays * 24 * 3_600_000;
 	}
 
 	#waitingOf(principalId: string): { files: number; bytes: number } {
@@ -303,11 +316,15 @@ export class Uploads {
 		return files;
 	}
 
-	/** Moves claimed uploads into the stored files, once their message is accepted. */
-	use(ids: readonly string[]): void {
+	/**
+	 * Moves claimed uploads into the stored files, once their message is accepted. `binding` ties
+	 * them to the host room the message is in, so only that room's readers are served them.
+	 */
+	use(ids: readonly string[], binding?: FileBinding): void {
 		for (const id of ids) {
 			this.#pending.delete(id);
-			this.#waiting.moveTo(id, this.#stored);
+			if (this.#waiting.moveTo(id, this.#stored) && binding)
+				this.#stored.bind(id, binding);
 		}
 	}
 
@@ -334,7 +351,11 @@ export class Uploads {
 		return { path };
 	}
 
-	/** Deletes the waiting uploads older than a day and the stored files older than 30 days; returns how many. */
+	/**
+	 * Deletes the waiting uploads older than a day and the stored files that are due; returns how
+	 * many. A file of an agent room is due after `keepDays` (default 30); a file bound to a host
+	 * room is due when its own expiry passes, and kept when it has none.
+	 */
 	sweep(): number {
 		const now = this.#now();
 		let dropped = 0;
@@ -343,7 +364,12 @@ export class Uploads {
 			this.#pending.delete(id);
 			dropped += 1;
 		}
-		for (const id of this.#stored.older(FILE_RETENTION_MS, now)) {
+		for (const id of this.#stored.ids()) {
+			const binding = this.#stored.binding(id);
+			const due = binding
+				? binding.expiresAt !== undefined && binding.expiresAt <= now
+				: (this.#stored.ageOf(id, now) ?? 0) > this.#keepMs;
+			if (!due) continue;
 			this.#stored.remove(id);
 			dropped += 1;
 		}