pi-roundtable-web 0.0.0-stage → 0.7.0

package/dist/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>Console</title>
+		
+	<link rel="stylesheet" crossorigin href="./chunk-e8z9q554.css"><script type="module" crossorigin src="./chunk-gkh6x5ag.js"></script></head>
+	<body>
+		<div id="root"></div>
+		
+	</body>
+</html>

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "pi-roundtable-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "pi-roundtable-web",
+	"version": "0.7.0",
+	"description": "An owner-only web console for pi-roundtable: conversations, transcripts, and memory notes, with live updates",
+	"type": "module",
+	"license": "MIT",
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/testing",
+		"dist",
+		"LICENSE",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wayne930242/pi-roundtable.git",
+		"directory": "packages/web"
+	},
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"scripts": {
+		"build": "bun scripts/build.ts",
+		"prepack": "bun scripts/build.ts",
+		"fixture": "bun scripts/fixture-host.ts",
+		"typecheck": "tsc --noEmit && tsc --noEmit -p web",
+		"lint": "biome check .",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"jose": "6.2.12"
+	},
+	"peerDependencies": {
+		"pi-roundtable": ">=0.7.0 <0.8.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"@types/bun": "1.4.2",
+		"@types/react": "19.3.0",
+		"@types/react-dom": "19.3.0",
+		"pi-roundtable": "0.7.0",
+		"react": "19.3.0",
+		"react-dom": "19.3.0",
+		"typescript": "7.0.2"
+	}
+}

package/src/api-types.ts

@@ -0,0 +1,128 @@
+// The console's API shapes, shared by the server (`src/`) and the page (`web/`). Times are ISO strings.
+
+/** The panes the console can show; the options choose which ones a host serves. */
+export const PANES = ["overview", "conversations", "notes"] as const;
+export type PaneName = (typeof PANES)[number];
+
+/** What the page needs before it can draw anything. */
+export interface ConfigView {
+	title: string;
+	panes: PaneName[];
+	/** The IANA zone the page formats times and event dates in: the host's `env.timeZone`. */
+	timeZone: string;
+}
+
+export type ChannelName =
+	| { kind: "dm"; name: string }
+	| { kind: "guild"; name: string; guild: string; guildId: string }
+	/** Discord no longer knows the channel. */
+	| { kind: "gone" }
+	/** Discord could not be asked, or the host has no Discord connection. */
+	| { kind: "unknown" };
+
+export interface ContextView {
+	tokens: number | null;
+	contextWindow: number;
+}
+
+export interface AgentView {
+	name: string;
+	displayName: string;
+	channelId?: string;
+	model: string;
+	thinking: string;
+	/** Channel id of its running turn. */
+	workingIn?: string;
+	waiting: number;
+	context?: ContextView;
+	lastActive?: string;
+	schedules: number;
+}
+
+export interface GroupView {
+	name: string;
+	displayName: string;
+	channelId: string;
+	members: string[];
+	host: string;
+	busy: number;
+	lastActive?: string;
+}
+
+export interface OverviewView {
+	guildId: string;
+	agents: AgentView[];
+	groups: GroupView[];
+}
+
+/** Who a stored conversation belongs to. */
+export type ConversationKind = "agent" | "group" | "owner" | "outside";
+
+export interface ConversationView {
+	/** The channel key: `discord:<id>`, `agentgroup:<channel>.<agent>`, or `mcp:<session>`. */
+	key: string;
+	kind: ConversationKind;
+	/** 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;
+	/** Discord conversations, group ones included. */
+	channel?: ChannelName;
+	/** Bytes of the live conversation; 0 when only archives are left. */
+	liveBytes: number;
+	archives: number;
+	lastActive?: string;
+	/** Outside-agent conversations only: up to 80 characters of the first message. */
+	firstMessage?: string;
+	startedAt?: string;
+	/** Turns running or waiting in the channel. */
+	busy: number;
+}
+
+export interface ConversationsView {
+	conversations: ConversationView[];
+}
+
+export type TranscriptRole = "user" | "assistant" | "tool" | "compaction";
+
+export interface TranscriptEntry {
+	role: TranscriptRole;
+	at?: string;
+	text: string;
+	/** What an assistant message called, by name with a short preview of the arguments. */
+	calls?: { name: string; preview: string }[];
+	/** The tool a `tool` entry answers. */
+	tool?: string;
+	failed?: boolean;
+}
+
+export interface TranscriptView {
+	conversation: ConversationView;
+	/** The names of the conversation's archives, newest first. */
+	archives: string[];
+	/** The archive being read; absent for the live conversation. */
+	archive?: string;
+	entries: TranscriptEntry[];
+	/** True when the file was longer than the console reads, so the oldest entries are missing. */
+	truncated: boolean;
+}
+
+export type NoteKind = "core" | "note" | "event";
+
+export interface NoteView {
+	id: number;
+	kind: NoteKind;
+	fact: string;
+	eventDate: string | null;
+}
+
+export interface NoteInput {
+	fact: string;
+	kind: NoteKind;
+	eventDate?: string;
+}
+
+/** Every error body the API returns. */
+export interface ApiError {
+	error: string;
+}

package/src/assets.ts

@@ -0,0 +1,47 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** One built file of the page. */
+export interface Asset {
+	body: Uint8Array;
+	type: string;
+}
+
+/** The page's files by their path under the mount, `index.html` included. */
+export type AssetBundle = ReadonlyMap<string, Asset>;
+
+/** Where `bun run build` leaves the page; the published package ships it ready-made. */
+export const BUILT_PAGE_DIR = fileURLToPath(
+	new URL("../dist/", import.meta.url),
+);
+
+/**
+ * Reads the built page into memory. A missing page throws, so a checkout that was never built
+ * stops the host at startup instead of serving a blank page.
+ */
+export function loadAssets(dir: string = BUILT_PAGE_DIR): AssetBundle {
+	let entries: ReturnType<typeof listFiles>;
+	try {
+		entries = listFiles(dir);
+	} catch {
+		throw new Error(
+			`the console page is not built: ${dir} does not exist. Run \`bun run build\` in the package, or install the published package, which ships it built.`,
+		);
+	}
+	const assets = new Map<string, Asset>();
+	for (const path of entries)
+		assets.set(relative(dir, path).split(sep).join("/"), {
+			body: readFileSync(path),
+			type: Bun.file(path).type,
+		});
+	if (!assets.has("index.html"))
+		throw new Error(`the console page is not built: ${dir} has no index.html`);
+	return assets;
+}
+
+function listFiles(dir: string): string[] {
+	return readdirSync(dir, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => join(entry.parentPath, entry.name));
+}

package/src/cloudflare-access.ts

@@ -0,0 +1,59 @@
+import { createRemoteJWKSet, type JWTVerifyGetKey, jwtVerify } from "jose";
+import { admit, type RequestVerifier, refuse } from "./verifier.ts";
+
+export interface CloudflareAccessOptions {
+	/** The Access team domain, such as `example.cloudflareaccess.com`. */
+	teamDomain: string;
+	/** The AUD tag of the Access application in front of the console. */
+	audience: string;
+	/** The email, or emails, Access may vouch for; compared without regard to case. */
+	email: string | readonly string[];
+	/** Replaceable in tests; the team's published signing keys otherwise. */
+	keys?: JWTVerifyGetKey;
+}
+
+const HEADER = "cf-access-jwt-assertion";
+
+/**
+ * Admits a request only when Cloudflare Access vouches for an allowed email: its
+ * `Cf-Access-Jwt-Assertion` header holds a token signed by the team's keys, issued by the team,
+ * for this application, naming that email. The token is checked on every request, so the
+ * console stays closed to a client that reaches it without passing through Access.
+ */
+export function cloudflareAccess(
+	options: CloudflareAccessOptions,
+): RequestVerifier {
+	const teamDomain = options.teamDomain.trim();
+	const audience = options.audience.trim();
+	const emails = (
+		typeof options.email === "string" ? [options.email] : options.email
+	).map((email) => email.trim().toLowerCase());
+	if (!teamDomain || teamDomain.includes("/"))
+		throw new Error(
+			"cloudflareAccess: teamDomain must be a host name such as example.cloudflareaccess.com",
+		);
+	if (!audience) throw new Error("cloudflareAccess: audience is empty");
+	if (emails.length === 0 || emails.some((email) => !email))
+		throw new Error("cloudflareAccess: email names no one");
+	const keys =
+		options.keys ??
+		createRemoteJWKSet(new URL(`https://${teamDomain}/cdn-cgi/access/certs`));
+	return async (request) => {
+		const token = request.headers.get(HEADER);
+		if (!token) return refuse("no Access token");
+		try {
+			const { payload } = await jwtVerify(token, keys, {
+				issuer: `https://${teamDomain}`,
+				audience,
+			});
+			if (
+				typeof payload.email !== "string" ||
+				!emails.includes(payload.email.toLowerCase())
+			)
+				return refuse("email not allowed");
+		} catch {
+			return refuse("invalid Access token");
+		}
+		return admit();
+	};
+}

package/src/console-api.ts

@@ -0,0 +1,354 @@
+import { join } from "node:path";
+import type {
+	AgentTeam,
+	ChannelKey,
+	Logger,
+	MemoryKind,
+	QueuePort,
+	SpeakerMemory,
+} from "pi-roundtable";
+import { MemoryError } from "pi-roundtable";
+import { thinkingLabel } from "pi-roundtable/kit";
+import type {
+	ApiError,
+	ChannelName,
+	ConfigView,
+	ConversationKind,
+	ConversationsView,
+	ConversationView,
+	NoteInput,
+	NoteView,
+	OverviewView,
+	PaneName,
+	TranscriptView,
+} from "./api-types.ts";
+import {
+	archiveNames,
+	conversationFiles,
+	parseKey,
+	readTranscript,
+	type StoredConversation,
+	storedConversations,
+} from "./conversations.ts";
+
+const NOTE_SEARCH_LIMIT = 500;
+/** The largest note body the console reads. */
+const MAX_BODY_BYTES = 64 * 1024;
+
+export interface ConsolePorts {
+	title: string;
+	timeZone: string;
+	panes: readonly PaneName[];
+	/** The host's `sessions/` directory. */
+	sessionsDir: string;
+	/** Present when the overview pane is served, or the agent server is there to classify channels. */
+	team?: Pick<AgentTeam, "status" | "owns" | "guildId">;
+	queue: Pick<QueuePort, "size">;
+	/** Undefined when Discord no longer knows the channel; throws when it cannot be asked. */
+	channelName?: (channelId: string) => Promise<ChannelName | undefined>;
+	/** The owner's memory; present when the notes pane is served. */
+	memory?: Pick<
+		SpeakerMemory,
+		"list" | "search" | "add" | "update" | "removeById"
+	>;
+	/** Conversations the console must not list or read. */
+	exclude?: (key: ChannelKey) => boolean;
+	/** Text a relayed message begins with, which is not the owner's words. */
+	relayNotes: readonly string[];
+	/** Called after a note is written, so every open page refreshes. */
+	changed(): void;
+	logger: Logger;
+}
+
+class HttpError extends Error {
+	constructor(
+		readonly status: number,
+		message: string,
+	) {
+		super(message);
+	}
+}
+
+const json = (body: unknown, status = 200) =>
+	Response.json(body, {
+		status,
+		headers: { "cache-control": "no-store" },
+	});
+
+/** Memory refusals as the Notes pane shows them. */
+const MEMORY_REASONS: Record<string, string> = {
+	"a memory fact cannot be empty": "The note cannot be empty.",
+	"an event needs its date as YYYY-MM-DD":
+		"An event needs its date as YYYY-MM-DD.",
+	"only an event has a date": "Only an event has a date.",
+};
+
+const memoryReason = (error: MemoryError): string =>
+	MEMORY_REASONS[error.message] ?? "The kind is not one of core, note, event.";
+
+const iso = (date: Date | undefined) => date?.toISOString();
+
+/**
+ * The console's JSON API under `<mount>/api/`. Every handler answers JSON; errors never repeat
+ * the request URL or headers.
+ */
+export class ConsoleApi {
+	readonly #ports: ConsolePorts;
+
+	constructor(ports: ConsolePorts) {
+		this.#ports = ports;
+	}
+
+	/** `path` is what follows `<mount>/api/`. */
+	async handle(request: Request, path: string): Promise<Response> {
+		try {
+			return await this.#route(request, path);
+		} catch (error) {
+			if (error instanceof HttpError)
+				return json({ error: error.message } satisfies ApiError, error.status);
+			if (error instanceof MemoryError)
+				return json({ error: memoryReason(error) } satisfies ApiError, 400);
+			// The URL stays out of the log: a path may hold something private.
+			this.#ports.logger.error({ err: error }, "console api failed");
+			return json(
+				{
+					error: "The console could not complete the request.",
+				} satisfies ApiError,
+				500,
+			);
+		}
+	}
+
+	#pane(name: PaneName): void {
+		if (!this.#ports.panes.includes(name))
+			throw new HttpError(404, "This pane is not served.");
+	}
+
+	async #route(request: Request, path: string): Promise<Response> {
+		const method = request.method;
+		let parts: string[];
+		try {
+			parts = path.split("/").filter(Boolean).map(decodeURIComponent);
+		} catch {
+			throw new HttpError(400, "The path is not valid.");
+		}
+		const [head, id] = parts;
+		if (method === "GET" && head === "config" && !id)
+			return json(this.config());
+		if (method === "GET" && head === "overview" && !id) {
+			this.#pane("overview");
+			return json(await this.overview());
+		}
+		if (method === "GET" && head === "conversations" && parts.length <= 2) {
+			this.#pane("conversations");
+			if (!id) return json(await this.conversations());
+			const archive = new URL(request.url).searchParams.get("archive");
+			return json(await this.transcript(id, archive ?? undefined));
+		}
+		if (head === "notes" && parts.length <= 2) {
+			this.#pane("notes");
+			return this.#notes(request, id);
+		}
+		throw new HttpError(404, "There is no such API.");
+	}
+
+	config(): ConfigView {
+		const { title, panes, timeZone } = this.#ports;
+		return { title, panes: [...panes], timeZone };
+	}
+
+	// ── Overview ───────────────────────────────────────────────────────────
+
+	async overview(): Promise<OverviewView> {
+		const { team } = this.#ports;
+		if (!team) throw new HttpError(404, "This pane is not served.");
+		const status = await team.status();
+		return {
+			guildId: team.guildId,
+			agents: status.agents.map((agent) => ({
+				name: agent.name,
+				displayName: agent.displayName,
+				...(agent.channelId ? { channelId: agent.channelId } : {}),
+				model: agent.model,
+				thinking: thinkingLabel(agent.thinking),
+				...(agent.workingIn ? { workingIn: agent.workingIn } : {}),
+				waiting: agent.waiting,
+				...(agent.context ? { context: agent.context } : {}),
+				...(agent.lastActive ? { lastActive: iso(agent.lastActive) } : {}),
+				schedules: agent.schedules,
+			})),
+			groups: status.groups.map((group) => ({
+				name: group.name,
+				displayName: group.displayName,
+				channelId: group.channelId,
+				members: group.members,
+				host: group.host,
+				busy: group.busy,
+				...(group.lastActive ? { lastActive: iso(group.lastActive) } : {}),
+			})),
+		};
+	}
+
+	// ── Conversations ──────────────────────────────────────────────────────
+
+	async conversations(): Promise<ConversationsView> {
+		const { sessionsDir, relayNotes, exclude } = this.#ports;
+		const stored = storedConversations(sessionsDir, {
+			excluded: (key) => exclude?.(key) ?? false,
+			relayNotes,
+		});
+		return {
+			conversations: await Promise.all(stored.map((c) => this.#view(c))),
+		};
+	}
+
+	async transcript(
+		key: string,
+		archive: string | undefined,
+	): Promise<TranscriptView> {
+		const { sessionsDir, relayNotes, exclude } = this.#ports;
+		const parsed = parseKey(key);
+		if (!parsed || exclude?.(key as ChannelKey))
+			throw new HttpError(404, "There is no such conversation.");
+		const dir = join(sessionsDir, parsed.dir);
+		const files = conversationFiles(dir);
+		if (!files) throw new HttpError(404, "There is no such conversation.");
+		const archives = archiveNames(dir);
+		// The archive is chosen from the folder's listing, never joined from the request.
+		if (archive !== undefined && !archives.includes(archive))
+			throw new HttpError(404, "There is no such archive.");
+		const { entries, truncated } = readTranscript(dir, archive, relayNotes);
+		return {
+			conversation: await this.#view({
+				key: key as ChannelKey,
+				kind: parsed.kind,
+				id: parsed.id,
+				...(parsed.member ? { member: parsed.member } : {}),
+				...files,
+			}),
+			archives,
+			...(archive !== undefined ? { archive } : {}),
+			entries,
+			truncated,
+		};
+	}
+
+	async #view(stored: StoredConversation): Promise<ConversationView> {
+		const { team, queue } = this.#ports;
+		const kind: ConversationKind =
+			stored.kind === "mcp"
+				? "outside"
+				: stored.kind === "group"
+					? "group"
+					: (team?.owns(stored.key) ?? "owner");
+		return {
+			key: stored.key,
+			kind,
+			id: stored.id,
+			...(stored.member ? { member: stored.member } : {}),
+			...(stored.kind === "mcp"
+				? {}
+				: { channel: await this.#name(stored.id) }),
+			liveBytes: stored.liveBytes,
+			archives: stored.archives,
+			...(stored.lastActive ? { lastActive: stored.lastActive } : {}),
+			...(stored.firstMessage ? { firstMessage: stored.firstMessage } : {}),
+			...(stored.startedAt ? { startedAt: stored.startedAt } : {}),
+			// A group's turns queue under the group channel, not under each member's conversation.
+			busy: queue.size(
+				stored.kind === "group" ? `discord:${stored.id}` : stored.key,
+			),
+		};
+	}
+
+	async #name(channelId: string): Promise<ChannelName> {
+		const lookup = this.#ports.channelName;
+		if (!lookup) return { kind: "unknown" };
+		try {
+			return (await lookup(channelId)) ?? { kind: "gone" };
+		} catch {
+			// Discord is reconnecting; the id is all the page can show until the next refresh.
+			return { kind: "unknown" };
+		}
+	}
+
+	// ── Notes ──────────────────────────────────────────────────────────────
+
+	async #notes(request: Request, id: string | undefined): Promise<Response> {
+		const { memory } = this.#ports;
+		if (!memory) throw new HttpError(404, "This pane is not served.");
+		const method = request.method;
+		if (!id) {
+			if (method === "GET") {
+				const query = new URL(request.url).searchParams.get("q")?.trim();
+				const notes: NoteView[] = query
+					? await memory.search(query, NOTE_SEARCH_LIMIT)
+					: await memory.list();
+				return json(notes);
+			}
+			if (method === "POST") {
+				const input = await noteInput(request);
+				const added = await memory.add(input.fact, input.kind, input.eventDate);
+				this.#ports.changed();
+				return json(added, 201);
+			}
+		} else {
+			const noteId = Number(id);
+			if (!Number.isSafeInteger(noteId))
+				throw new HttpError(404, "There is no such note.");
+			if (method === "PATCH") {
+				const updated = await memory.update(noteId, await noteInput(request));
+				if (!updated) throw new HttpError(404, "There is no such note.");
+				this.#ports.changed();
+				return json(updated);
+			}
+			if (method === "DELETE") {
+				if (!(await memory.removeById(noteId)))
+					throw new HttpError(404, "There is no such note.");
+				this.#ports.changed();
+				return json({ deleted: noteId });
+			}
+		}
+		throw new HttpError(405, "This method is not supported.");
+	}
+}
+
+/** The JSON body, read in chunks so a body past the limit is refused without being held whole. */
+async function readBody(request: Request): Promise<unknown> {
+	const tooLarge = () => new HttpError(413, "The request is too large.");
+	if (Number(request.headers.get("content-length") ?? 0) > MAX_BODY_BYTES)
+		throw tooLarge();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	if (request.body)
+		for await (const chunk of request.body) {
+			size += chunk.byteLength;
+			if (size > MAX_BODY_BYTES) throw tooLarge();
+			chunks.push(chunk);
+		}
+	try {
+		return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+async function noteInput(request: Request): Promise<{
+	fact: string;
+	kind: MemoryKind;
+	eventDate?: string;
+}> {
+	const body = await readBody(request);
+	if (typeof body !== "object" || body === null)
+		throw new HttpError(400, "The body is not valid.");
+	const { fact, kind, eventDate } = body as Partial<NoteInput>;
+	if (typeof fact !== "string" || typeof kind !== "string")
+		throw new HttpError(400, "The body is not valid.");
+	if (eventDate !== undefined && typeof eventDate !== "string")
+		throw new HttpError(400, "The date is not valid.");
+	return {
+		fact,
+		kind: kind as MemoryKind,
+		...(eventDate ? { eventDate } : {}),
+	};
+}