pi-roundtable-web 0.0.0-stage → 0.7.2

package/src/console-server.ts

@@ -0,0 +1,214 @@
+import type { HttpRoute, Logger } from "pi-roundtable";
+import type { AssetBundle } from "./assets.ts";
+import type { ConsoleApi } from "./console-api.ts";
+import type { RequestVerifier } from "./verifier.ts";
+
+const encoder = new TextEncoder();
+/** Changes closer together than this reach the page as one event. */
+const COALESCE_MS = 250;
+/** Events a stream may hold unread before its client is cut off; it reconnects and refetches. */
+const STREAM_BACKLOG = 16;
+/** Keeps the stream open through proxies that close streams idle for about a minute or two. */
+const PING_MS = 30_000;
+/** Open event streams; one more is refused, so a client cannot hold every connection. */
+const MAX_STREAMS = 32;
+const READ_METHODS = new Set(["GET", "HEAD"]);
+
+const SECURITY_HEADERS = {
+	"x-content-type-options": "nosniff",
+	"referrer-policy": "same-origin",
+};
+
+const PAGE_HEADERS = {
+	"content-type": "text/html;charset=utf-8",
+	"cache-control": "no-cache",
+	"content-security-policy":
+		"default-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'self'; frame-ancestors 'none'",
+};
+
+export interface ConsoleServerOptions {
+	/** The path the console is served under, without a trailing slash: `/console`. */
+	mount: string;
+	assets: AssetBundle;
+	verifier: RequestVerifier;
+	/** The console's own origin; requests that change data must come from it. */
+	origin: string;
+	api: Pick<ConsoleApi, "handle">;
+	/** Registers the listener with every source whose change the console shows. */
+	subscribe(listener: () => void): void;
+	logger: Logger;
+	/** How long changes are gathered into one event; default 250 ms. Tests set it lower. */
+	coalesceMs?: number;
+}
+
+/**
+ * The console on the host's listener: `<mount>` redirects to `<mount>/`, and everything under
+ * it needs the verifier to vouch for the owner. A request that changes data must also carry the
+ * console's own `Origin`.
+ */
+export class ConsoleServer {
+	readonly #options: ConsoleServerOptions;
+	readonly #base: string;
+	readonly #streams = new Set<ReadableStreamDefaultController<Uint8Array>>();
+	#pending: ReturnType<typeof setTimeout> | undefined;
+	#ping: ReturnType<typeof setInterval> | undefined;
+
+	constructor(options: ConsoleServerOptions) {
+		this.#options = options;
+		this.#base = `${options.mount}/`;
+		options.subscribe(() => this.#changed());
+	}
+
+	routes(listener: string): HttpRoute[] {
+		const handle = (request: Request) => this.handle(request);
+		return [
+			{
+				name: "web-console-redirect",
+				listener,
+				path: { exact: this.#options.mount },
+				handle,
+			},
+			{
+				name: "web-console",
+				listener,
+				path: { prefix: this.#base },
+				handle,
+			},
+		];
+	}
+
+	start(): void {
+		this.#ping = setInterval(() => this.#send(": ping\n\n"), PING_MS);
+	}
+
+	/** Ends the event streams; the listener may already have closed their connections. */
+	stop(): void {
+		clearInterval(this.#ping);
+		clearTimeout(this.#pending);
+		this.#pending = undefined;
+		for (const stream of this.#streams) {
+			try {
+				stream.close();
+			} catch {
+				// Its connection is gone, and the stream with it.
+			}
+		}
+		this.#streams.clear();
+	}
+
+	async handle(request: Request): Promise<Response> {
+		const response = await this.#respond(request);
+		for (const [name, value] of Object.entries(SECURITY_HEADERS))
+			response.headers.set(name, value);
+		return response;
+	}
+
+	async #respond(request: Request): Promise<Response> {
+		// pi-lens-ignore: unchecked-throwing-call -- the server builds request.url, always an absolute URL
+		const path = new URL(request.url).pathname;
+		if (path === this.#options.mount)
+			return new Response(null, {
+				status: 302,
+				headers: { location: this.#base },
+			});
+		if (!path.startsWith(this.#base))
+			return new Response("Not found", { status: 404 });
+		const refusal = await this.#refusal(request);
+		if (refusal !== undefined) {
+			this.#options.logger.warn({ refusal }, "console request refused");
+			return new Response("Forbidden", {
+				status: 403,
+				headers: { "cache-control": "no-store" },
+			});
+		}
+		const rest = path.slice(this.#base.length);
+		if (rest === "api/events" && request.method === "GET")
+			return this.#events();
+		if (rest.startsWith("api/"))
+			return this.#options.api.handle(request, rest.slice("api/".length));
+		if (!READ_METHODS.has(request.method))
+			return new Response("Method not allowed", { status: 405 });
+		if (rest === "" || rest === "index.html") {
+			const page = this.#options.assets.get("index.html");
+			if (page) return new Response(page.body, { headers: PAGE_HEADERS });
+		}
+		const asset = this.#options.assets.get(rest);
+		if (asset && rest !== "index.html")
+			return new Response(asset.body, {
+				headers: {
+					"content-type": asset.type,
+					"cache-control": "private, max-age=31536000, immutable",
+				},
+			});
+		return new Response("Not found", { status: 404 });
+	}
+
+	/** Undefined when the request may pass, otherwise why not; never throws. */
+	async #refusal(request: Request): Promise<string | undefined> {
+		try {
+			const verdict = await this.#options.verifier(request);
+			if (!verdict.admitted) return String(verdict.reason);
+		} catch {
+			// A verifier that fails admits no one.
+			return "verifier failed";
+		}
+		if (
+			!READ_METHODS.has(request.method) &&
+			request.headers.get("origin") !== this.#options.origin
+		)
+			return "foreign origin";
+		return undefined;
+	}
+
+	/** A server-sent event stream that says `changed` whenever the console may differ. */
+	#events(): Response {
+		if (this.#streams.size >= MAX_STREAMS)
+			return new Response("Too many event streams", { status: 503 });
+		let controller: ReadableStreamDefaultController<Uint8Array> | undefined;
+		const body = new ReadableStream<Uint8Array>(
+			{
+				start: (c) => {
+					controller = c;
+					this.#streams.add(c);
+					c.enqueue(encoder.encode("retry: 3000\n\n"));
+				},
+				cancel: () => {
+					if (controller) this.#streams.delete(controller);
+				},
+			},
+			new CountQueuingStrategy({ highWaterMark: STREAM_BACKLOG }),
+		);
+		return new Response(body, {
+			headers: {
+				"content-type": "text/event-stream",
+				"cache-control": "no-store",
+				"x-accel-buffering": "no",
+			},
+		});
+	}
+
+	#changed(): void {
+		if (this.#pending || this.#streams.size === 0) return;
+		this.#pending = setTimeout(() => {
+			this.#pending = undefined;
+			this.#send("event: changed\ndata: {}\n\n");
+		}, this.#options.coalesceMs ?? COALESCE_MS);
+	}
+
+	#send(text: string): void {
+		const chunk = encoder.encode(text);
+		for (const stream of this.#streams) {
+			try {
+				// An event only says "refetch", so a client that has not read its backlog is not worth
+				// buffering for: it is closed, and its page reconnects after the retry delay.
+				if ((stream.desiredSize ?? 0) <= 0) {
+					this.#streams.delete(stream);
+					stream.close();
+				} else stream.enqueue(chunk);
+			} catch {
+				// The page went away; its stream is closed.
+				this.#streams.delete(stream);
+			}
+		}
+	}
+}

package/src/conversations.ts

@@ -0,0 +1,383 @@
+import {
+	closeSync,
+	existsSync,
+	fstatSync,
+	openSync,
+	readdirSync,
+	readFileSync,
+	readSync,
+	statSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { ChannelKey } from "pi-roundtable";
+import { textOf } from "pi-roundtable/kit";
+import type { TranscriptEntry } from "./api-types.ts";
+
+const FIRST_MESSAGE_CHARS = 80;
+/** The most a transcript request reads from disk, newest files first. */
+const MAX_TRANSCRIPT_BYTES = 8 * 1024 * 1024;
+/** How much of a conversation's first file the list reads to find its first message. */
+const OPENING_BYTES = 256 * 1024;
+/** The most entries a transcript returns; the oldest are dropped. */
+const MAX_ENTRIES = 1000;
+const MAX_TEXT_CHARS = 20_000;
+const MAX_TOOL_TEXT_CHARS = 2000;
+const MAX_PREVIEW_CHARS = 200;
+
+const DISCORD_DIR = /^discord_(\d{17,20})$/;
+const MCP_DIR =
+	/^mcp_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+const GROUP_DIR = /^agentgroup_(\d{17,20})_([A-Za-z0-9_-]+)$/;
+const DISCORD_KEY = /^discord:(\d{17,20})$/;
+const GROUP_KEY = /^agentgroup:(\d{17,20})\.([A-Za-z0-9_-]+)$/;
+const MCP_KEY =
+	/^mcp:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
+
+/** Facts about a conversation's files. */
+export interface ConversationFiles {
+	/** Bytes of the live conversation; 0 when only archives are left. */
+	liveBytes: number;
+	archives: number;
+	lastActive?: string;
+}
+
+/** The kinds of session directory the console reads. */
+export type StoredKind = "discord" | "group" | "mcp";
+
+/** An owner, agent, group-member, or outside-agent conversation found on disk. */
+export interface StoredConversation extends ConversationFiles {
+	key: ChannelKey;
+	kind: StoredKind;
+	/** The Discord channel id, or the outside agent's session id. */
+	id: string;
+	/** Group conversations only: the agent whose conversation inside the group this is. */
+	member?: string;
+	/** Outside-agent conversations only. */
+	firstMessage?: string;
+	startedAt?: string;
+}
+
+/** The session directory a channel key names, or undefined when the key is not one the console reads. */
+export function parseKey(
+	key: string,
+): { dir: string; kind: StoredKind; id: string; member?: string } | undefined {
+	const discord = DISCORD_KEY.exec(key)?.[1];
+	if (discord)
+		return { dir: `discord_${discord}`, kind: "discord", id: discord };
+	const mcp = MCP_KEY.exec(key)?.[1];
+	if (mcp) return { dir: `mcp_${mcp}`, kind: "mcp", id: mcp };
+	const group = GROUP_KEY.exec(key);
+	if (group?.[1] && group[2])
+		return {
+			dir: `agentgroup_${group[1]}_${group[2]}`,
+			kind: "group",
+			id: group[1],
+			member: group[2],
+		};
+	return undefined;
+}
+
+/**
+ * The live `.jsonl` files at a session directory's top level and its `archive/<time>/`
+ * folders, as `archiveSessions` leaves them. Undefined when the directory does not exist.
+ */
+export function conversationFiles(dir: string): ConversationFiles | undefined {
+	if (!existsSync(dir)) return undefined;
+	let liveBytes = 0;
+	let newest = 0;
+	for (const file of readdirSync(dir)) {
+		if (!file.endsWith(".jsonl")) continue;
+		const stat = statSync(join(dir, file));
+		liveBytes += stat.size;
+		newest = Math.max(newest, stat.mtimeMs);
+	}
+	const archiveDir = join(dir, "archive");
+	const archives = existsSync(archiveDir)
+		? readdirSync(archiveDir, { withFileTypes: true }).filter((entry) =>
+				entry.isDirectory(),
+			)
+		: [];
+	if (newest === 0)
+		for (const archive of archives)
+			newest = Math.max(
+				newest,
+				statSync(join(archiveDir, archive.name)).mtimeMs,
+			);
+	return {
+		liveBytes,
+		archives: archives.length,
+		...(newest > 0 ? { lastActive: new Date(newest).toISOString() } : {}),
+	};
+}
+
+interface SessionLine {
+	type?: unknown;
+	timestamp?: unknown;
+	summary?: unknown;
+	message?: {
+		role?: unknown;
+		content?: unknown;
+		toolName?: unknown;
+		isError?: unknown;
+	};
+}
+
+const clip = (text: string, limit: number): string =>
+	text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+
+/** The text after a relay note, when the message starts with one of them. */
+function withoutRelayNote(text: string, notes: readonly string[]): string {
+	const note = notes.find((prefix) => prefix && text.startsWith(prefix));
+	return (note ? text.slice(note.length) : text).trim();
+}
+
+/** The `.jsonl` file names directly in a directory, oldest first; names start with their creation time. */
+function sessionFiles(dir: string): string[] {
+	return readdirSync(dir)
+		.filter((file) => file.endsWith(".jsonl"))
+		.sort();
+}
+
+/** The whole lines in the first `limit` bytes of a file; a line the limit cuts is left out. */
+function readHead(path: string, limit: number): string[] {
+	const fd = openSync(path, "r");
+	try {
+		const { size } = fstatSync(fd);
+		const buffer = Buffer.alloc(Math.min(size, limit));
+		readSync(fd, buffer, 0, buffer.length, 0);
+		const lines = buffer.toString("utf8").split("\n");
+		if (size > limit) lines.pop();
+		return lines;
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/**
+ * When the conversation started and its first user message, relay notes removed: from the
+ * live conversation, or from the oldest archive once it has been started over.
+ */
+function opening(
+	dir: string,
+	relayNotes: readonly string[],
+): { firstMessage?: string; startedAt?: string } {
+	const archiveDir = join(dir, "archive");
+	const first = sessionFiles(dir)[0];
+	let file = first ? join(dir, first) : undefined;
+	if (!file && existsSync(archiveDir))
+		for (const archive of readdirSync(archiveDir).sort()) {
+			const name = sessionFiles(join(archiveDir, archive))[0];
+			if (name) {
+				file = join(archiveDir, archive, name);
+				break;
+			}
+		}
+	if (!file) return {};
+	const result: { firstMessage?: string; startedAt?: string } = {};
+	for (const line of readHead(file, OPENING_BYTES)) {
+		if (!line.trim()) continue;
+		let entry: SessionLine;
+		try {
+			entry = JSON.parse(line);
+		} catch {
+			// A line cut off mid-write ends what can be read.
+			break;
+		}
+		if (entry.type === "session" && typeof entry.timestamp === "string")
+			result.startedAt = entry.timestamp;
+		if (entry.type === "message" && entry.message?.role === "user") {
+			result.firstMessage = clip(
+				withoutRelayNote(textOf(entry.message.content), relayNotes),
+				FIRST_MESSAGE_CHARS,
+			);
+			break;
+		}
+	}
+	return result;
+}
+
+/** Who a session directory's name says it belongs to; undefined for any other directory. */
+function parseDirectory(
+	name: string,
+): Pick<StoredConversation, "key" | "kind" | "id" | "member"> | undefined {
+	const discord = DISCORD_DIR.exec(name)?.[1];
+	if (discord)
+		return { key: `discord:${discord}`, kind: "discord", id: discord };
+	const mcp = MCP_DIR.exec(name)?.[1];
+	if (mcp) return { key: `mcp:${mcp}`, kind: "mcp", id: mcp };
+	const group = GROUP_DIR.exec(name);
+	if (group?.[1] && group[2])
+		return {
+			key: `agentgroup:${group[1]}.${group[2]}`,
+			kind: "group",
+			id: group[1],
+			member: group[2],
+		};
+	return undefined;
+}
+
+/**
+ * Agent, owner, group-member, and outside-agent conversations (`discord_<channel>`,
+ * `agentgroup_<channel>_<agent>`, `mcp_<session>`) under the host's `sessions/` directory, minus
+ * the channels `excluded` claims.
+ */
+export function storedConversations(
+	sessionsDir: string,
+	options: {
+		excluded: (key: ChannelKey) => boolean;
+		relayNotes: readonly string[];
+	},
+): StoredConversation[] {
+	if (!existsSync(sessionsDir)) return [];
+	const found: StoredConversation[] = [];
+	for (const entry of readdirSync(sessionsDir, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		const identity = parseDirectory(entry.name);
+		if (!identity || options.excluded(identity.key)) continue;
+		const dir = join(sessionsDir, entry.name);
+		const files = conversationFiles(dir);
+		if (!files) continue;
+		found.push({
+			...identity,
+			...files,
+			...(identity.kind === "mcp" ? opening(dir, options.relayNotes) : {}),
+		});
+	}
+	return found.sort((a, b) =>
+		(b.lastActive ?? "").localeCompare(a.lastActive ?? ""),
+	);
+}
+
+/** The archive folders of a conversation, newest first. */
+export function archiveNames(dir: string): string[] {
+	const archiveDir = join(dir, "archive");
+	if (!existsSync(archiveDir)) return [];
+	return readdirSync(archiveDir, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.sort()
+		.reverse();
+}
+
+/**
+ * The last `limit` bytes of a file as text, from the first whole line when the file is longer,
+ * and how many bytes were read from disk, which is what the caller's budget pays for.
+ */
+function readTail(
+	path: string,
+	limit: number,
+): { text: string; cut: boolean; read: number } {
+	const fd = openSync(path, "r");
+	try {
+		const { size } = fstatSync(fd);
+		if (size <= limit)
+			return { text: readFileSync(fd, "utf8"), cut: false, read: size };
+		const buffer = Buffer.alloc(limit);
+		readSync(fd, buffer, 0, limit, size - limit);
+		const text = buffer.toString("utf8");
+		return { text: text.slice(text.indexOf("\n") + 1), cut: true, read: limit };
+	} finally {
+		closeSync(fd);
+	}
+}
+
+function callPreview(args: unknown): string {
+	try {
+		return clip(JSON.stringify(args) ?? "", MAX_PREVIEW_CHARS);
+	} catch {
+		return "";
+	}
+}
+
+/** One session line as a transcript entry; undefined for lines the console does not show. */
+function entryOf(
+	line: SessionLine,
+	relayNotes: readonly string[],
+): TranscriptEntry | undefined {
+	const at = typeof line.timestamp === "string" ? line.timestamp : undefined;
+	const base = at ? { at } : {};
+	if (line.type === "compaction" && typeof line.summary === "string")
+		return {
+			role: "compaction",
+			...base,
+			text: clip(line.summary, MAX_TOOL_TEXT_CHARS),
+		};
+	if (line.type !== "message" || !line.message) return undefined;
+	const { role, content } = line.message;
+	if (role === "user") {
+		const text = withoutRelayNote(textOf(content), relayNotes);
+		return text
+			? { role: "user", ...base, text: clip(text, MAX_TEXT_CHARS) }
+			: undefined;
+	}
+	if (role === "assistant") {
+		const text = textOf(content).trim();
+		const calls = Array.isArray(content)
+			? content.flatMap((part) =>
+					part?.type === "toolCall" && typeof part.name === "string"
+						? [{ name: part.name, preview: callPreview(part.arguments) }]
+						: [],
+				)
+			: [];
+		if (!text && calls.length === 0) return undefined;
+		return {
+			role: "assistant",
+			...base,
+			text: clip(text, MAX_TEXT_CHARS),
+			...(calls.length > 0 ? { calls } : {}),
+		};
+	}
+	if (role === "toolResult")
+		return {
+			role: "tool",
+			...base,
+			text: clip(textOf(content), MAX_TOOL_TEXT_CHARS),
+			...(typeof line.message.toolName === "string"
+				? { tool: line.message.toolName }
+				: {}),
+			...(line.message.isError === true ? { failed: true } : {}),
+		};
+	return undefined;
+}
+
+/**
+ * The entries of a conversation's live files, or of one archive, oldest first. Reads newest
+ * files first until the byte budget is spent, so a very long conversation shows its end.
+ */
+export function readTranscript(
+	dir: string,
+	archive: string | undefined,
+	relayNotes: readonly string[],
+): { entries: TranscriptEntry[]; truncated: boolean } {
+	const folder = archive ? join(dir, "archive", archive) : dir;
+	const files = sessionFiles(folder).reverse();
+	let budget = MAX_TRANSCRIPT_BYTES;
+	let truncated = false;
+	const chunks: TranscriptEntry[][] = [];
+	for (const file of files) {
+		if (budget <= 0) {
+			truncated = true;
+			break;
+		}
+		const { text, cut, read } = readTail(join(folder, file), budget);
+		budget -= read;
+		if (cut) truncated = true;
+		const entries: TranscriptEntry[] = [];
+		for (const raw of text.split("\n")) {
+			if (!raw.trim()) continue;
+			let line: SessionLine;
+			try {
+				line = JSON.parse(raw);
+			} catch {
+				// A line cut off mid-write has no entry.
+				continue;
+			}
+			const entry = entryOf(line, relayNotes);
+			if (entry) entries.push(entry);
+		}
+		chunks.push(entries);
+	}
+	const all = chunks.reverse().flat();
+	if (all.length > MAX_ENTRIES) truncated = true;
+	return { entries: all.slice(-MAX_ENTRIES), truncated };
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// The package's one entry: the plugin, its options, and the built-in verifier.
+
+export type {
+	AgentView,
+	ApiError,
+	ChannelName,
+	ConfigView,
+	ContextView,
+	ConversationKind,
+	ConversationsView,
+	ConversationView,
+	GroupView,
+	NoteInput,
+	NoteKind,
+	NoteView,
+	OverviewView,
+	PaneName,
+	TranscriptEntry,
+	TranscriptRole,
+	TranscriptView,
+} from "./api-types.ts";
+export { PANES } from "./api-types.ts";
+export type { CloudflareAccessOptions } from "./cloudflare-access.ts";
+export { cloudflareAccess } from "./cloudflare-access.ts";
+export type { WebConsoleOptions } from "./options.ts";
+export { DEFAULT_RELAY_NOTE } from "./options.ts";
+export type { RequestVerifier, Verdict } from "./verifier.ts";
+export { admit, refuse } from "./verifier.ts";
+export { webConsole } from "./web-plugin.ts";