pi-roundtable-web 0.24.2 → 0.26.0

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,
 		);
 	}