pi-roundtable-web 0.22.5 → 0.23.1

package/src/app/files.ts

@@ -0,0 +1,262 @@
+import {
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import { open } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+import type { RoomFile } from "../api-types.ts";
+
+/** A stored file's id: the uuid the store made. */
+const FILE_ID =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/** The image types shown in the page itself; every other file is a download. */
+const INLINE_TYPES = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif",
+]);
+
+/** How long a reply's or a sent message's file stays: 30 days. */
+export const FILE_RETENTION_MS = 30 * 24 * 3_600_000;
+
+/** The types a file name suggests, for files an agent's turn made. */
+const BY_EXTENSION: Record<string, string> = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".webp": "image/webp",
+	".gif": "image/gif",
+	".json": "application/json",
+	".txt": "text/plain",
+	".md": "text/markdown",
+	".csv": "text/csv",
+	".pdf": "application/pdf",
+	".html": "text/html",
+	".svg": "image/svg+xml",
+};
+
+/** The type a file name suggests; unknown names are plain bytes. */
+export const typeByName = (name: string): string =>
+	BY_EXTENSION[extname(name).toLowerCase()] ?? "application/octet-stream";
+
+/** A file name safe to keep and to show: no path, no control characters, at most 120 characters. */
+export function safeName(name: string): string {
+	const cleaned = Array.from(basename(name.replaceAll("\\", "/")))
+		.filter((char) => {
+			const code = char.codePointAt(0) ?? 0;
+			// Controls, and the bidirectional overrides that make a name read as another one.
+			return (
+				code > 0x1f &&
+				code !== 0x7f &&
+				!(code >= 0x202a && code <= 0x202e) &&
+				!(code >= 0x2066 && code <= 0x2069)
+			);
+		})
+		.join("")
+		.trim();
+	const cut = Array.from(cleaned).slice(0, 120).join("");
+	return cut === "" || cut === "." || cut === ".." ? "file" : cut;
+}
+
+export const isFileId = (id: string): boolean => FILE_ID.test(id);
+
+interface Meta {
+	name: string;
+	type: string;
+	size: number;
+}
+
+/** A file being written as its bytes arrive; `finish` makes it a stored file, `abort` leaves nothing. */
+export interface FileWriter {
+	readonly id: string;
+	/** Bytes written so far. */
+	readonly size: number;
+	write(chunk: Uint8Array): Promise<void>;
+	finish(name: string, type: string): Promise<RoomFile>;
+	abort(): Promise<void>;
+}
+
+/**
+ * A directory of files kept by id, each with a small record of its name and type beside it.
+ * Both stores of the app, the files of replies and sent messages and the uploads waiting for a
+ * message, are one of these.
+ */
+export class FileDir {
+	readonly dir: string;
+
+	constructor(dir: string) {
+		this.dir = dir;
+	}
+
+	#path(id: string): string {
+		return join(this.dir, id);
+	}
+
+	/** Keeps the bytes under a new id. */
+	put(
+		name: string,
+		type: string,
+		bytes: Uint8Array,
+		id = crypto.randomUUID(),
+	): RoomFile {
+		mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+		const meta: Meta = { name: safeName(name), type, size: bytes.byteLength };
+		writeFileSync(this.#path(id), bytes, { mode: 0o600 });
+		writeFileSync(`${this.#path(id)}.json`, JSON.stringify(meta), {
+			mode: 0o600,
+		});
+		return { id, ...meta };
+	}
+
+	/** Starts a file under a new id whose bytes arrive in pieces, so it is never held whole. */
+	async begin(): Promise<FileWriter> {
+		mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+		const id = crypto.randomUUID();
+		const path = this.#path(id);
+		const handle = await open(path, "wx", 0o600);
+		let size = 0;
+		let ended = false;
+		const close = async () => {
+			if (ended) return false;
+			ended = true;
+			await handle.close();
+			return true;
+		};
+		return {
+			id,
+			get size() {
+				return size;
+			},
+			write: async (chunk) => {
+				await handle.write(chunk);
+				size += chunk.byteLength;
+			},
+			finish: async (name, type) => {
+				await close();
+				const meta: Meta = { name: safeName(name), type, size };
+				writeFileSync(`${path}.json`, JSON.stringify(meta), { mode: 0o600 });
+				return { id, ...meta };
+			},
+			abort: async () => {
+				await close().catch(() => undefined);
+				rmSync(path, { force: true });
+				rmSync(`${path}.json`, { force: true });
+			},
+		};
+	}
+
+	/** The file as a blob that is read as it is sent, or undefined when there is none. */
+	blob(id: string): Blob | undefined {
+		if (!isFileId(id) || !existsSync(this.#path(id))) return undefined;
+		return Bun.file(this.#path(id));
+	}
+
+	meta(id: string): RoomFile | undefined {
+		if (!isFileId(id)) return undefined;
+		try {
+			const meta = JSON.parse(
+				readFileSync(`${this.#path(id)}.json`, "utf8"),
+			) as Meta;
+			return { id, name: meta.name, type: meta.type, size: meta.size };
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** The absolute path of the file, or undefined when there is no regular file under the id. */
+	pathOf(id: string): string | undefined {
+		if (!isFileId(id)) return undefined;
+		const path = resolve(this.#path(id));
+		try {
+			return lstatSync(path).isFile() ? path : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	bytes(id: string): Uint8Array | undefined {
+		if (!isFileId(id) || !existsSync(this.#path(id))) return undefined;
+		try {
+			return readFileSync(this.#path(id));
+		} catch {
+			return undefined;
+		}
+	}
+
+	/** Moves a file, with its record, into another directory under the same id. */
+	moveTo(id: string, other: FileDir): boolean {
+		if (!isFileId(id) || !existsSync(this.#path(id))) return false;
+		mkdirSync(other.dir, { recursive: true, mode: 0o700 });
+		renameSync(this.#path(id), other.#path(id));
+		renameSync(`${this.#path(id)}.json`, `${other.#path(id)}.json`);
+		return true;
+	}
+
+	remove(id: string): void {
+		if (!isFileId(id)) return;
+		rmSync(this.#path(id), { force: true });
+		rmSync(`${this.#path(id)}.json`, { force: true });
+	}
+
+	/** Ids of the files older than `maxAgeMs`, by their modification time. */
+	older(maxAgeMs: number, now: number): string[] {
+		let names: string[];
+		try {
+			names = readdirSync(this.dir);
+		} catch {
+			return [];
+		}
+		return names
+			.filter((name) => isFileId(name))
+			.filter((name) => {
+				try {
+					return now - statSync(this.#path(name)).mtimeMs > maxAgeMs;
+				} catch {
+					return false;
+				}
+			});
+	}
+
+	/** Every file's id. */
+	ids(): string[] {
+		try {
+			return readdirSync(this.dir).filter((name) => isFileId(name));
+		} catch {
+			return [];
+		}
+	}
+}
+
+/**
+ * The response for a stored file: a download, except for the four image types the page shows,
+ * never interpreted as a page (`sandbox`, `nosniff`).
+ */
+export function fileResponse(meta: RoomFile, body: Blob): Response {
+	const inline = INLINE_TYPES.has(meta.type);
+	// RFC 5987 leaves `'`, `(`, `)` and `*` out of a value's characters; encodeURIComponent keeps them.
+	const encoded = encodeURIComponent(meta.name).replace(
+		/['()*]/g,
+		(char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`,
+	);
+	return new Response(body, {
+		headers: {
+			"content-type": inline ? meta.type : "application/octet-stream",
+			"content-disposition": inline
+				? "inline"
+				: `attachment; filename*=UTF-8''${encoded}`,
+			"content-security-policy": "sandbox",
+			"x-content-type-options": "nosniff",
+			"cache-control": "private, max-age=3600",
+			"content-length": String(body.size),
+		},
+	});
+}

package/src/app/frames.ts

@@ -0,0 +1,132 @@
+import type {
+	ApprovalDetails,
+	ApprovalWording,
+	OwnerQuestion,
+	Questionnaire,
+} from "pi-roundtable";
+import {
+	APPROVAL_MAX_BYTES,
+	type PromptApproval,
+	type PromptFrame,
+} from "../api-types.ts";
+
+/**
+ * The approval as the frame carries it: whole while its JSON is within `APPROVAL_MAX_BYTES`.
+ * Over that, each string value of the input is cut to the most code points that fit, marked
+ * `… [N chars]`, and `truncated` is set; an input that does not fit even then is sent as `{}`
+ * with no files. The copy text is informational, so it is carried after the input is settled
+ * and only if it fits then, never at the input's cost. The card's `message` always accompanies it.
+ */
+export function boundedApproval(details: ApprovalDetails): PromptApproval {
+	const size = (value: unknown) =>
+		new TextEncoder().encode(JSON.stringify(value)).length;
+	if (size(details) <= APPROVAL_MAX_BYTES) return details;
+	const { copy, ...withoutCopy } = details;
+	const bounded = boundedWithoutCopy(withoutCopy, size);
+	if (!copy) return bounded;
+	const candidate: PromptApproval = { ...bounded, copy };
+	return size(candidate) <= APPROVAL_MAX_BYTES ? candidate : bounded;
+}
+
+function boundedWithoutCopy(
+	details: Omit<ApprovalDetails, "copy">,
+	size: (value: unknown) => number,
+): PromptApproval {
+	if (size(details) <= APPROVAL_MAX_BYTES) return details;
+	const { files: _files, ...base } = details;
+	const fits = (limit: number): PromptApproval | undefined => {
+		const candidate: PromptApproval = {
+			...base,
+			input: cutStrings(details.input, limit),
+			truncated: true,
+		};
+		return size(candidate) <= APPROVAL_MAX_BYTES ? candidate : undefined;
+	};
+	let low = 0;
+	let high = longestString(details.input);
+	let best = fits(0);
+	if (!best) return { ...base, input: {}, truncated: true };
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		const candidate = fits(mid);
+		if (candidate) {
+			best = candidate;
+			low = mid;
+		} else high = mid - 1;
+	}
+	return best;
+}
+
+const pointsOf = (text: string) => Array.from(text).length;
+
+// pi-lens-ignore: no-unknown-parameters — tool input is untyped model JSON; this is where it is read
+function longestString(value: unknown): number {
+	if (typeof value === "string") return pointsOf(value);
+	if (Array.isArray(value))
+		return Math.max(0, ...value.map((v: unknown) => longestString(v)));
+	if (value && typeof value === "object")
+		return Math.max(
+			0,
+			...Object.values(value).map((v: unknown) => longestString(v)),
+		);
+	return 0;
+}
+
+/** `value` with every string longer than `limit` code points cut to its start plus `… [N chars]`. */
+function cutStrings<T>(value: T, limit: number): T {
+	if (typeof value === "string") {
+		if (value.length <= limit) return value;
+		const points = Array.from(value);
+		if (points.length <= limit) return value;
+		return `${points.slice(0, limit).join("")}… [${points.length} chars]` as T;
+	}
+	if (Array.isArray(value))
+		return value.map((v: unknown) => cutStrings(v, limit)) as T;
+	if (value && typeof value === "object")
+		return Object.fromEntries(
+			Object.entries(value).map(([k, v]) => [k, cutStrings(v, limit)]),
+		) as T;
+	return value;
+}
+
+/** An `ask` card's frame, from the core's question. */
+export function askFrame(
+	id: string,
+	title: string,
+	question: OwnerQuestion,
+): Extract<PromptFrame, { kind: "ask" }> {
+	return {
+		id,
+		kind: "ask",
+		title,
+		question: question.question,
+		options: question.options.map((option) => ({ ...option })),
+		multi: question.multi,
+		allowOther: question.allowOther,
+	};
+}
+
+/** A `questionnaire` card's frame, the core's questions copied verbatim. */
+export function questionnaireFrame(
+	id: string,
+	title: string,
+	questionnaire: Questionnaire,
+): Extract<PromptFrame, { kind: "questionnaire" }> {
+	return {
+		id,
+		kind: "questionnaire",
+		title,
+		questions: questionnaire.questions.map((q) => ({
+			...q,
+			options: q.options.map((option) => ({ ...option })),
+		})),
+	};
+}
+
+/** The card's own words, copied so a later change of the caller's object cannot reach the frame. */
+export function wordingFrame(
+	wording: ApprovalWording,
+): NonNullable<Extract<PromptFrame, { kind: "approval" }>["wording"]> {
+	const { approve, decline, footer, approved, declined } = wording;
+	return { approve, decline, footer, approved, declined };
+}

package/src/app/multipart.ts

@@ -0,0 +1,172 @@
+/** A body that is not the multipart form it says it is. */
+export class MultipartError extends Error {
+	override name = "MultipartError";
+}
+
+/** What a part of the form says about itself. */
+export interface PartHeaders {
+	/** The form field's name. */
+	name: string;
+	/** The file's name, for a file part. */
+	filename: string | undefined;
+	/** The part's content type, lower-cased, without parameters. */
+	contentType: string;
+}
+
+/** Takes the part's bytes as they arrive; `end` runs once its last byte did, `abort` when the body ended early or failed. */
+export interface PartSink {
+	write(chunk: Uint8Array): void | Promise<void>;
+	end(): void | Promise<void>;
+	abort(): void | Promise<void>;
+}
+
+/** The longest a part's header block may be. */
+const MAX_HEADER_BYTES = 16 * 1024;
+/** The most bytes of text before the first boundary that are skipped; a form has none. */
+const MAX_PREAMBLE_BYTES = 8 * 1024;
+
+const encoder = new TextEncoder();
+
+/** The boundary a `multipart/form-data` content type names; undefined when it names none. */
+export function boundaryOf(contentType: string | null): string | undefined {
+	if (!contentType) return undefined;
+	const match =
+		/^multipart\/form-data\s*;(?:.*;)?\s*boundary=(?:"([^"]{1,200})"|([^\s;"]{1,200}))/i.exec(
+			contentType,
+		);
+	return match?.[1] ?? match?.[2];
+}
+
+function headersOf(block: string): PartHeaders {
+	const map = new Map<string, string>();
+	for (const line of block.split("\r\n")) {
+		const colon = line.indexOf(":");
+		if (colon > 0)
+			map.set(line.slice(0, colon).trim().toLowerCase(), line.slice(colon + 1));
+	}
+	const disposition = map.get("content-disposition") ?? "";
+	const param = (key: string) => {
+		const match = new RegExp(`;\\s*${key}="((?:[^"\\\\]|\\\\.)*)"`, "i").exec(
+			disposition,
+		);
+		return match?.[1]
+			?.replaceAll("%22", '"')
+			.replaceAll("%0D", "\r")
+			.replaceAll("%0A", "\n")
+			.replace(/\\(.)/g, "$1");
+	};
+	return {
+		name: param("name") ?? "",
+		filename: param("filename"),
+		contentType:
+			map.get("content-type")?.split(";")[0]?.trim().toLowerCase() ?? "",
+	};
+}
+
+const find = (haystack: Uint8Array, needle: Uint8Array, from = 0): number =>
+	Buffer.from(
+		haystack.buffer,
+		haystack.byteOffset,
+		haystack.byteLength,
+	).indexOf(needle, from);
+
+const join = (a: Uint8Array, b: Uint8Array): Uint8Array => {
+	if (a.byteLength === 0) return b;
+	const both = new Uint8Array(a.byteLength + b.byteLength);
+	both.set(a, 0);
+	both.set(b, a.byteLength);
+	return both;
+};
+
+/**
+ * Reads a `multipart/form-data` body as a stream, handing each part's bytes to the sink that
+ * `onPart` returns, so no part is ever held whole: memory stays at a chunk and a boundary's
+ * length. A part `onPart` gives no sink for is read past and dropped. Throws `MultipartError`
+ * for a body that is not well formed, and whatever a sink or `onPart` throws; the part being
+ * written is aborted first.
+ */
+export async function readMultipart(
+	body: ReadableStream<Uint8Array>,
+	boundary: string,
+	onPart: (
+		headers: PartHeaders,
+	) => PartSink | undefined | Promise<PartSink | undefined>,
+): Promise<void> {
+	const delimiter = encoder.encode(`\r\n--${boundary}`);
+	const headerEnd = encoder.encode("\r\n\r\n");
+	// The first boundary is not preceded by a line break; pretending one came keeps one search for all.
+	let buffer: Uint8Array = encoder.encode("\r\n");
+	let state: "preamble" | "after-delimiter" | "headers" | "body" | "done" =
+		"preamble";
+	let sink: PartSink | undefined;
+	let dropped = false;
+	const reader = body.getReader();
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			// After the closing boundary what follows (the epilogue) is read and dropped, never gathered.
+			if (value && state !== "done") buffer = join(buffer, value);
+			// Everything the buffer can settle is settled before the next chunk is read.
+			for (let progressed = true; progressed && state !== "done"; ) {
+				progressed = false;
+				if (state === "preamble") {
+					const at = find(buffer, delimiter);
+					if (at >= 0) {
+						buffer = buffer.subarray(at + delimiter.byteLength);
+						state = "after-delimiter";
+						progressed = true;
+					} else if (buffer.byteLength > MAX_PREAMBLE_BYTES) {
+						buffer = buffer.subarray(buffer.byteLength - delimiter.byteLength);
+					}
+				} else if (state === "after-delimiter") {
+					if (buffer.byteLength >= 2) {
+						const head = String.fromCharCode(buffer[0] ?? 0, buffer[1] ?? 0);
+						if (head === "--") {
+							state = "done";
+							buffer = new Uint8Array(0);
+						} else if (head === "\r\n") {
+							buffer = buffer.subarray(2);
+							state = "headers";
+							progressed = true;
+						} else throw new MultipartError("A boundary is not well formed.");
+					}
+				} else if (state === "headers") {
+					const at = find(buffer, headerEnd);
+					if (at >= 0) {
+						const block = new TextDecoder().decode(buffer.subarray(0, at));
+						buffer = buffer.subarray(at + headerEnd.byteLength);
+						sink = await onPart(headersOf(block));
+						dropped = sink === undefined;
+						state = "body";
+						progressed = true;
+					} else if (buffer.byteLength > MAX_HEADER_BYTES)
+						throw new MultipartError("A part's headers are too long.");
+				} else if (state === "body") {
+					const at = find(buffer, delimiter);
+					if (at >= 0) {
+						if (!dropped && at > 0) await sink?.write(buffer.subarray(0, at));
+						await sink?.end();
+						sink = undefined;
+						buffer = buffer.subarray(at + delimiter.byteLength);
+						state = "after-delimiter";
+						progressed = true;
+					} else {
+						// Hold back what could be the start of the delimiter.
+						const safe = buffer.byteLength - (delimiter.byteLength - 1);
+						if (safe > 0) {
+							if (!dropped) await sink?.write(buffer.subarray(0, safe));
+							buffer = buffer.subarray(safe);
+						}
+					}
+				}
+			}
+			if (done) break;
+		}
+		if (state !== "done") throw new MultipartError("The form is cut short.");
+	} catch (error) {
+		await sink?.abort();
+		throw error;
+	} finally {
+		reader.releaseLock();
+	}
+}

package/src/app/presence.ts

@@ -0,0 +1,73 @@
+import type { AgentTeam, Logger } from "pi-roundtable";
+import type { ServerFrame } from "../api-types.ts";
+import type { Sockets } from "./sockets.ts";
+
+/** Changes closer together than this reach the sockets as one `presence` frame. */
+const PRESENCE_COALESCE_MS = 250;
+
+type PresenceFrame = Extract<ServerFrame, { type: "presence" }>;
+
+export interface PresenceOptions {
+	team: Pick<AgentTeam, "status" | "onChange">;
+	sockets: Sockets;
+	/** The agents working in the app's own rooms now, which the team's status does not list. */
+	working(): ReadonlySet<string>;
+	logger: Logger;
+	/** How long changes are gathered; default 250 ms. */
+	coalesceMs?: number;
+}
+
+/**
+ * Which agents are busy, anywhere: a turn in a Discord channel shows in the team's status, and a
+ * turn in an app room shows in the surface. A frame goes out only when the table differs from the
+ * one last sent, so a turn's churn costs the sockets nothing.
+ */
+export class Presence {
+	readonly #options: PresenceOptions;
+	#pending: ReturnType<typeof setTimeout> | undefined;
+	#last = "";
+	#stopped = false;
+
+	constructor(options: PresenceOptions) {
+		this.#options = options;
+		options.team.onChange(() => this.schedule());
+	}
+
+	/** The table now, as a frame. */
+	async frame(): Promise<PresenceFrame> {
+		const { team, working } = this.#options;
+		const status = await team.status();
+		const here = working();
+		const agents: PresenceFrame["agents"] = {};
+		for (const agent of status.agents)
+			agents[agent.name] = {
+				busy: agent.workingIn !== undefined || here.has(agent.name),
+			};
+		return { type: "presence", agents };
+	}
+
+	/** Sends the table to every socket once changes settle, if it changed. */
+	schedule(): void {
+		if (this.#pending || this.#stopped) return;
+		this.#pending = setTimeout(() => {
+			this.#pending = undefined;
+			this.#send().catch((error: unknown) =>
+				this.#options.logger.warn({ err: error }, "presence was not sent"),
+			);
+		}, this.#options.coalesceMs ?? PRESENCE_COALESCE_MS);
+	}
+
+	async #send(): Promise<void> {
+		const frame = await this.frame();
+		const text = JSON.stringify(frame.agents);
+		if (text === this.#last || this.#stopped) return;
+		this.#last = text;
+		this.#options.sockets.broadcast(frame);
+	}
+
+	stop(): void {
+		this.#stopped = true;
+		clearTimeout(this.#pending);
+		this.#pending = undefined;
+	}
+}