pi-roundtable-web 0.22.5 → 0.23.1

package/src/app/protocol.ts

@@ -0,0 +1,144 @@
+import { QUESTIONNAIRE_LIMITS } from "pi-roundtable";
+import {
+	type ClientFrame,
+	MAX_MESSAGE_FILES,
+	type PromptAnswer,
+} from "../api-types.ts";
+
+export {
+	APP_CLOSE_EXPIRED,
+	APP_PROTOCOL,
+	APP_PROTOCOL_VERSION,
+	APPROVAL_MAX_BYTES,
+	type ClientFrame,
+	MAX_MESSAGE_CHARS,
+	MAX_MESSAGE_FILES,
+	type ServerFrame,
+} from "../api-types.ts";
+
+/** The longest room key, prompt id, upload id or client reference accepted. */
+const ID_CHARS = 200;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isId = (value: unknown): value is string =>
+	typeof value === "string" && value.length > 0 && value.length <= ID_CHARS;
+
+const isText = (value: unknown): value is string => typeof value === "string";
+
+const optional = <T>(value: unknown, check: (v: unknown) => v is T) =>
+	value === undefined || check(value);
+
+function parseAnswer(value: unknown): PromptAnswer | undefined {
+	if (!isRecord(value) || !Array.isArray(value.choices)) return undefined;
+	const { choices, text } = value;
+	if (!choices.every(isText) || !optional(text, isText)) return undefined;
+	return {
+		choices: choices as string[],
+		...(text === undefined ? {} : { text }),
+	};
+}
+
+function parseAnswers(value: Record<string, unknown>): ClientFrame | undefined {
+	const { prompt, answers, note } = value;
+	if (!isId(prompt) || !Array.isArray(answers)) return undefined;
+	if (answers.length < 1 || answers.length > QUESTIONNAIRE_LIMITS.questions)
+		return undefined;
+	if (!optional(note, isText)) return undefined;
+	const parsed: (PromptAnswer | null)[] = [];
+	for (const answer of answers as unknown[]) {
+		if (answer === null) {
+			parsed.push(null);
+			continue;
+		}
+		const one = parseAnswer(answer);
+		if (!one) return undefined;
+		parsed.push(one);
+	}
+	return {
+		type: "answers",
+		prompt,
+		answers: parsed,
+		...(note === undefined ? {} : { note }),
+	};
+}
+
+/** One client frame, checked field by field; undefined for anything else. */
+export function parseClientFrame(
+	raw: string | Uint8Array,
+): ClientFrame | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(
+			typeof raw === "string" ? raw : new TextDecoder().decode(raw),
+		);
+	} catch {
+		return undefined;
+	}
+	if (!isRecord(value)) return undefined;
+	switch (value.type) {
+		case "hello": {
+			const { visible, focus } = value;
+			if (typeof visible !== "boolean" || !optional(focus, isId))
+				return undefined;
+			return {
+				type: "hello",
+				visible,
+				...(focus === undefined ? {} : { focus }),
+			};
+		}
+		case "visibility":
+			return typeof value.visible === "boolean"
+				? { type: "visibility", visible: value.visible }
+				: undefined;
+		case "focus":
+			if (!optional(value.room, isId)) return undefined;
+			return {
+				type: "focus",
+				...(value.room === undefined ? {} : { room: value.room as string }),
+			};
+		case "send": {
+			const { id, room, text, uploads } = value;
+			if (!isId(id) || !isId(room) || !isText(text)) return undefined;
+			if (
+				uploads !== undefined &&
+				!(
+					Array.isArray(uploads) &&
+					uploads.length <= MAX_MESSAGE_FILES &&
+					uploads.every(isId)
+				)
+			)
+				return undefined;
+			return {
+				type: "send",
+				id,
+				room,
+				text,
+				...(uploads === undefined || uploads.length === 0
+					? {}
+					: { uploads: uploads as string[] }),
+			};
+		}
+		case "stop":
+			return isId(value.room) ? { type: "stop", room: value.room } : undefined;
+		case "approval":
+			return isId(value.prompt) && typeof value.approved === "boolean"
+				? { type: "approval", prompt: value.prompt, approved: value.approved }
+				: undefined;
+		case "answer": {
+			const answer = parseAnswer(value.answer);
+			return isId(value.prompt) && answer
+				? { type: "answer", prompt: value.prompt, answer }
+				: undefined;
+		}
+		case "answers":
+			return parseAnswers(value);
+		case "cancel":
+			return isId(value.prompt)
+				? { type: "cancel", prompt: value.prompt }
+				: undefined;
+		default:
+			return undefined;
+	}
+}

package/src/app/room-log.ts

@@ -0,0 +1,137 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+import type { RoomFile, RoomMessage } from "../api-types.ts";
+
+/** A message to store; the log numbers it and stamps its time. */
+export interface NewRoomMessage {
+	room: string;
+	kind: RoomMessage["kind"];
+	principalId?: string;
+	agent?: string;
+	author: string;
+	text: string;
+	files?: RoomFile[];
+}
+
+interface Row {
+	id: string | number | bigint;
+	room: string;
+	kind: RoomMessage["kind"];
+	principal_id: string | null;
+	agent: string | null;
+	author_name: string;
+	text: string;
+	files: RoomFile[] | string;
+	created_at: Date;
+}
+
+/** The most messages one page of history holds. */
+export const PAGE_LIMIT = 100;
+
+function messageOf(row: Row): RoomMessage {
+	const files =
+		typeof row.files === "string"
+			? (JSON.parse(row.files) as RoomFile[])
+			: row.files;
+	return {
+		id: Number(row.id),
+		room: row.room,
+		kind: row.kind,
+		...(row.principal_id === null ? {} : { principalId: row.principal_id }),
+		...(row.agent === null ? {} : { agent: row.agent }),
+		author: row.author_name,
+		text: row.text,
+		files,
+		at: row.created_at.toISOString(),
+	};
+}
+
+/**
+ * The app's rooms' messages, kept in `web_room_messages`: what the owner wrote, what the agents
+ * answered, and the lines the server wrote, such as a conversation's start-over divider. Rooms
+ * are separate from the Discord channels' history, which the conversations pane reads as
+ * transcripts.
+ */
+export class RoomLog {
+	readonly #sql: SQL;
+
+	constructor(sql: SQL) {
+		this.#sql = sql;
+	}
+
+	/** The log's table. */
+	static readonly migration: Migration = {
+		name: "web-room-messages",
+		up: async (sql) => {
+			await sql`
+				CREATE TABLE IF NOT EXISTS web_room_messages (
+					id bigserial PRIMARY KEY,
+					room text NOT NULL,
+					kind text NOT NULL,
+					principal_id text,
+					agent text,
+					author_name text NOT NULL,
+					text text NOT NULL,
+					files jsonb NOT NULL DEFAULT '[]',
+					created_at timestamptz NOT NULL DEFAULT now()
+				)`;
+			await sql`CREATE INDEX IF NOT EXISTS web_room_messages_room_id ON web_room_messages (room, id)`;
+		},
+	};
+
+	async append(message: NewRoomMessage): Promise<RoomMessage> {
+		const files = JSON.stringify(message.files ?? []);
+		const [row]: Row[] = await this.#sql`
+			INSERT INTO web_room_messages (room, kind, principal_id, agent, author_name, text, files)
+			VALUES (${message.room}, ${message.kind}, ${message.principalId ?? null},
+				${message.agent ?? null}, ${message.author}, ${message.text}, ${files}::jsonb)
+			RETURNING *`;
+		if (!row) throw new Error("the room log stored nothing");
+		return messageOf(row);
+	}
+
+	/** Changes the text of a message stored in the room; undefined when the room holds no such message. */
+	async edit(
+		room: string,
+		id: number,
+		text: string,
+	): Promise<RoomMessage | undefined> {
+		const [row]: Row[] = await this.#sql`
+			UPDATE web_room_messages SET text = ${text}
+			WHERE id = ${id} AND room = ${room} RETURNING *`;
+		return row && messageOf(row);
+	}
+
+	/** The newest `limit` messages older than `before` (all of them when absent), oldest first. */
+	async page(
+		room: string,
+		before: number | undefined,
+		limit: number,
+	): Promise<{ messages: RoomMessage[]; more: boolean }> {
+		const count = Math.min(Math.max(Math.trunc(limit), 1), PAGE_LIMIT);
+		const rows: Row[] =
+			before === undefined
+				? await this.#sql`
+					SELECT * FROM web_room_messages WHERE room = ${room}
+					ORDER BY id DESC LIMIT ${count + 1}`
+				: await this.#sql`
+					SELECT * FROM web_room_messages WHERE room = ${room} AND id < ${before}
+					ORDER BY id DESC LIMIT ${count + 1}`;
+		return {
+			messages: rows.slice(0, count).map(messageOf).reverse(),
+			more: rows.length > count,
+		};
+	}
+
+	/** The newest message of each of the rooms that has one. */
+	async lastOf(rooms: readonly string[]): Promise<Map<string, RoomMessage>> {
+		const found = new Map<string, RoomMessage>();
+		if (rooms.length === 0) return found;
+		const rows: Row[] = await this.#sql`
+			SELECT DISTINCT ON (room) * FROM web_room_messages
+			WHERE room IN ${this.#sql(rooms)}
+			ORDER BY room, id DESC`;
+		for (const row of rows) found.set(row.room, messageOf(row));
+		return found;
+	}
+}

package/src/app/rooms.ts

@@ -0,0 +1,189 @@
+import type {
+	Agent,
+	AgentDirectory,
+	AgentGroup,
+	AgentTeam,
+	AvatarStudio,
+	ChannelKey,
+	ConversationModes,
+} from "pi-roundtable";
+import {
+	agentRoomKey,
+	channelKey,
+	characterOf,
+	groupRoomKey,
+	roomOf,
+} from "pi-roundtable";
+import type { RoomKind, RoomView } from "../api-types.ts";
+import type { RoomLog } from "./room-log.ts";
+import type { WebThreads } from "./threads.ts";
+
+/** A room of the app that exists: what it is, and what it is called. */
+export interface ResolvedRoom {
+	key: ChannelKey;
+	kind: RoomKind;
+	/** The agent's or group's name; a thread's `thread.<uuid>`. */
+	name: string;
+	displayName: string;
+	/** A thread's room is read only. */
+	readOnly: boolean;
+}
+
+export interface RoomsOptions {
+	surface: string;
+	/** The mount, whose `avatars/` serves the pictures. */
+	mount: string;
+	directory: Pick<AgentDirectory, "agents" | "agent" | "groups" | "group">;
+	team: Pick<AgentTeam, "coordinator">;
+	avatars: Pick<AvatarStudio, "url">;
+	threads: Pick<WebThreads, "get" | "list">;
+	log: Pick<RoomLog, "lastOf">;
+	modes: Pick<ConversationModes, "peek">;
+	activity(
+		room: ChannelKey,
+	): Pick<RoomView, "typing" | "stoppable" | "phase" | "agent">;
+}
+
+const THREAD_ID = /^thread\.[0-9a-f-]{36}$/;
+
+/**
+ * The rooms of the app: Home (the coordinator's), one per active agent, one per active group,
+ * and the dispatch threads: the open ones and the latest closed ones. A key a client names is a room only when it is one of these on
+ * this surface, whose agent or group exists; no other surface's key ever is.
+ */
+export class Rooms {
+	readonly #options: RoomsOptions;
+
+	constructor(options: RoomsOptions) {
+		this.#options = options;
+	}
+
+	/** Whether the key is on this surface, whatever it names. */
+	ownsKey(key: string): boolean {
+		return key.startsWith(`${this.#options.surface}:`);
+	}
+
+	/** The room a key names, or undefined when it is none of the app's. */
+	async resolve(key: string): Promise<ResolvedRoom | undefined> {
+		if (!this.ownsKey(key)) return undefined;
+		const { surface, directory, threads } = this.#options;
+		const room = key as ChannelKey;
+		const named = roomOf(room, [surface]);
+		if (named?.kind === "agent") {
+			const agent = directory.agent(named.name);
+			return agent?.status === "active"
+				? {
+						key: room,
+						kind: "agent",
+						name: agent.name,
+						displayName: agent.displayName,
+						readOnly: false,
+					}
+				: undefined;
+		}
+		if (named?.kind === "group") {
+			const group = directory.group(named.name);
+			return group?.status === "active"
+				? {
+						key: room,
+						kind: "group",
+						name: group.name,
+						displayName: group.displayName,
+						readOnly: false,
+					}
+				: undefined;
+		}
+		const id = key.slice(surface.length + 1);
+		if (!THREAD_ID.test(id)) return undefined;
+		const thread = await threads.get(id);
+		// A closed thread stays a room the page can read; nobody can write in it.
+		return thread
+			? {
+					key: room,
+					kind: "thread",
+					name: thread.id,
+					displayName: thread.title,
+					readOnly: true,
+				}
+			: undefined;
+	}
+
+	/** The home room: the coordinator's, else the first active agent's. */
+	homeKey(): ChannelKey | undefined {
+		const { directory, team, surface } = this.#options;
+		const coordinator = team.coordinator();
+		const home =
+			(coordinator ? directory.agent(coordinator) : undefined) ??
+			directory.agents().find((agent) => agent.status === "active");
+		return home?.status === "active"
+			? agentRoomKey(surface, home.name)
+			: undefined;
+	}
+
+	/** The agent whose avatar path to show, as a path under the mount. */
+	avatarOf(agent: Agent): string {
+		// The studio gives a full URL with a public address and a bare path without one.
+		const path = /\/avatars\/[^/?#]+$/.exec(
+			this.#options.avatars.url(agent.avatarHash),
+		)?.[0];
+		return `${this.#options.mount}${path ?? "/avatars/missing.png"}`;
+	}
+
+	async list(): Promise<RoomView[]> {
+		const { surface, directory, modes, activity, log, threads } = this.#options;
+		const home = this.homeKey();
+		const agents = directory.agents().filter((a) => a.status === "active");
+		const groups = directory.groups().filter((g) => g.status === "active");
+		const shown = await threads.list();
+		const view = (
+			key: ChannelKey,
+			rest: Pick<RoomView, "kind" | "name" | "displayName"> & Partial<RoomView>,
+		): RoomView => {
+			const { yolo, longRunning } = modes.peek(key);
+			return {
+				home: key === home,
+				readOnly: false,
+				mode: { yolo, longRunning },
+				...activity(key),
+				...rest,
+				key,
+			};
+		};
+		const rooms: RoomView[] = [
+			...agents.map((agent: Agent) =>
+				view(agentRoomKey(surface, agent.name), {
+					kind: "agent",
+					name: agent.name,
+					displayName: agent.displayName,
+					avatar: this.avatarOf(agent),
+					character: characterOf(agent),
+				}),
+			),
+			...groups.map((group: AgentGroup) =>
+				view(groupRoomKey(surface, group.name), {
+					kind: "group",
+					name: group.name,
+					displayName: group.displayName,
+					members: [...group.members],
+				}),
+			),
+			...shown.map((thread) =>
+				view(channelKey(surface, thread.id), {
+					kind: "thread",
+					name: thread.id,
+					displayName: thread.title,
+					parent: thread.parent,
+					readOnly: true,
+					...(thread.open ? {} : { closed: true }),
+				}),
+			),
+		];
+		// Home first; the others keep the team's order.
+		rooms.sort((a, b) => Number(b.home) - Number(a.home));
+		const last = await log.lastOf(rooms.map((room) => room.key));
+		return rooms.map((room) => {
+			const message = last.get(room.key);
+			return message ? { ...room, last: message } : room;
+		});
+	}
+}