pi-roundtable-webchat 0.8.0

package/src/prompts.ts

@@ -0,0 +1,198 @@
+import {
+	type Approval,
+	type OwnerAnswer,
+	type OwnerPrompts,
+	type OwnerQuestion,
+	type Speaker,
+	TIERS,
+	type Tier,
+} from "pi-roundtable";
+import type {
+	ErrorCode,
+	PromptFrame,
+	PromptOutcome,
+	ServerFrame,
+} from "./protocol.ts";
+
+/** Who answers: the conversation's person, at their tier as of the answer. */
+export interface Answerer {
+	id: string;
+	tier: Tier;
+}
+
+interface Open {
+	conversation: string;
+	principal: string;
+	frame: PromptFrame;
+	/** The lowest tier that may approve; questions have none. */
+	minTier?: Tier;
+	settle(outcome: PromptOutcome, answer?: OwnerAnswer): void;
+}
+
+export interface PromptDeskOptions {
+	/** Sends a frame to every connection of a person. */
+	send(principal: string, frame: ServerFrame): void;
+	/** An unanswered prompt expires after this long. */
+	timeoutMs: number;
+}
+
+const atLeast = (tier: Tier, least: Tier) =>
+	TIERS.indexOf(tier) >= TIERS.indexOf(least);
+
+/**
+ * The approvals and questions open in web conversations. A prompt goes to every connection of
+ * the conversation's person, survives a reconnect (each `ready` sends the open ones again), and
+ * closes when answered, after `timeoutMs` (expired), or when the turn stops (cancelled). Only the
+ * conversation's person may answer, and an approval only at the tier it needs.
+ */
+export class PromptDesk {
+	readonly #open = new Map<string, Open>();
+	readonly #options: PromptDeskOptions;
+
+	constructor(options: PromptDeskOptions) {
+		this.#options = options;
+	}
+
+	/**
+	 * The prompts of a conversation for the speaker whose turn runs there. An approval whose tier
+	 * the speaker lacks expires at once without being shown: no one else can answer in a private
+	 * conversation, so the call stays held, as an unanswered card leaves it.
+	 */
+	prompts(conversation: string, speaker: Speaker): OwnerPrompts {
+		return {
+			confirm: async (title, message, signal, minTier = "owner") => {
+				if (!atLeast(speaker.tier, minTier)) return "expired";
+				const outcome = await this.#ask(
+					conversation,
+					speaker.id,
+					(id) => ({ id, kind: "approval", title, message }),
+					signal,
+					minTier,
+				);
+				return toApproval(outcome.outcome);
+			},
+			ask: async (title, question, signal) => {
+				const { outcome, answer } = await this.#ask(
+					conversation,
+					speaker.id,
+					(id) => questionFrame(id, title, question),
+					signal,
+				);
+				return outcome === "answered" ? answer : undefined;
+			},
+		};
+	}
+
+	/** The open prompts of a person, as frames to send again when they connect. */
+	openFor(principal: string): ServerFrame[] {
+		return [...this.#open.values()]
+			.filter((open) => open.principal === principal)
+			.map((open) => ({
+				type: "prompt",
+				conversation: open.conversation,
+				prompt: open.frame,
+			}));
+	}
+
+	/** Approves or declines; an error code when the prompt is not an approval this person may answer. */
+	approve(
+		from: Answerer,
+		prompt: string,
+		approved: boolean,
+	): ErrorCode | undefined {
+		const open = this.#open.get(prompt);
+		if (open?.frame.kind !== "approval") return "unknown_prompt";
+		if (open.principal !== from.id) return "forbidden";
+		if (open.minTier && !atLeast(from.tier, open.minTier)) return "forbidden";
+		open.settle(approved ? "approved" : "declined");
+		return undefined;
+	}
+
+	/** Answers a question; an error code when the answer does not fit the question or the person may not answer it. */
+	answer(
+		from: Answerer,
+		prompt: string,
+		answer: OwnerAnswer,
+	): ErrorCode | undefined {
+		const open = this.#open.get(prompt);
+		if (open?.frame.kind !== "ask") return "unknown_prompt";
+		if (open.principal !== from.id) return "forbidden";
+		if (!fits(open.frame, answer)) return "bad_frame";
+		open.settle("answered", answer);
+		return undefined;
+	}
+
+	#ask(
+		conversation: string,
+		principal: string,
+		frameOf: (id: string) => PromptFrame,
+		signal: AbortSignal | undefined,
+		minTier?: Tier,
+	): Promise<{ outcome: PromptOutcome; answer?: OwnerAnswer }> {
+		const { send, timeoutMs } = this.#options;
+		if (signal?.aborted) return Promise.resolve({ outcome: "cancelled" });
+		return new Promise((resolve) => {
+			const id = crypto.randomUUID();
+			const frame = frameOf(id);
+			const onAbort = () => settle("cancelled");
+			const timer = setTimeout(() => settle("expired"), timeoutMs);
+			const settle = (outcome: PromptOutcome, answer?: OwnerAnswer) => {
+				if (!this.#open.delete(id)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				send(principal, {
+					type: "prompt_closed",
+					conversation,
+					prompt: id,
+					outcome,
+				});
+				resolve(answer ? { outcome, answer } : { outcome });
+			};
+			this.#open.set(id, {
+				conversation,
+				principal,
+				frame,
+				...(minTier ? { minTier } : {}),
+				settle,
+			});
+			signal?.addEventListener("abort", onAbort, { once: true });
+			send(principal, { type: "prompt", conversation, prompt: frame });
+		});
+	}
+}
+
+function toApproval(outcome: PromptOutcome): Approval {
+	if (outcome === "approved" || outcome === "declined") return outcome;
+	return outcome === "cancelled" ? "cancelled" : "expired";
+}
+
+function questionFrame(
+	id: string,
+	title: string,
+	question: OwnerQuestion,
+): PromptFrame {
+	return {
+		id,
+		kind: "ask",
+		title,
+		question: question.question,
+		options: question.options.map((option) => ({ ...option })),
+		multi: question.multi,
+		allowOther: question.allowOther,
+	};
+}
+
+/** Whether an answer is one the question allows: offered labels, one unless multi, own text only where allowed. */
+function fits(
+	frame: Extract<PromptFrame, { kind: "ask" }>,
+	answer: OwnerAnswer,
+): boolean {
+	const labels = frame.options.map((option) => option.label);
+	const text = answer.text?.trim();
+	if (!answer.choices.every((choice) => labels.includes(choice))) return false;
+	if (new Set(answer.choices).size !== answer.choices.length) return false;
+	if (!frame.multi && answer.choices.length > 1) return false;
+	if (labels.length === 0) return answer.choices.length === 0 && Boolean(text);
+	if (text && !frame.allowOther) return false;
+	return answer.choices.length > 0 || Boolean(text);
+}

package/src/protocol.ts

@@ -0,0 +1,202 @@
+import type { AskOption, Tier, TurnProgress } from "pi-roundtable";
+
+/**
+ * The WebSocket subprotocol a client offers, and the server echoes, for this version of the
+ * protocol. A later incompatible version gets a new name, so an old client is refused at the
+ * handshake rather than misreading frames.
+ */
+export const WEBCHAT_PROTOCOL = "roundtable.webchat.v1";
+
+/** The version `ready` reports. */
+export const WEBCHAT_PROTOCOL_VERSION = 1;
+
+/** The subprotocol that carries a one-time ticket: `ticket.<ticket>`, offered beside `WEBCHAT_PROTOCOL`. */
+export const TICKET_PROTOCOL_PREFIX = "ticket.";
+
+/** Close codes the server uses besides the standard ones. */
+export const CLOSE_CODES = Object.freeze({
+	/** The token expired without a fresh `auth`, or a fresh one was refused. */
+	tokenExpired: 4401,
+	/** The person is no longer admitted: the policy gives them no tier, or a fresh token names someone else. */
+	notAdmitted: 4403,
+});
+
+/** A persona a client may open a conversation with. */
+export interface PersonaSummary {
+	kind: string;
+	label: string;
+}
+
+/** A file a reply carries, inline. */
+export interface ReplyFileFrame {
+	name: string;
+	/** The bytes, base64. */
+	data: string;
+}
+
+/** An approval or a question the conversation's turn asks the person. */
+export type PromptFrame =
+	| { id: string; kind: "approval"; title: string; message: string }
+	| {
+			id: string;
+			kind: "ask";
+			title: string;
+			question: string;
+			/** None means a free-text answer. */
+			options: readonly AskOption[];
+			multi: boolean;
+			allowOther: boolean;
+	  };
+
+/** How a prompt closed. */
+export type PromptOutcome =
+	| "approved"
+	| "declined"
+	| "answered"
+	| "expired"
+	| "cancelled";
+
+/** Why the server refused a frame or a request. */
+export type ErrorCode =
+	| "bad_frame"
+	| "unknown_conversation"
+	| "forbidden"
+	| "unknown_persona"
+	| "unknown_prompt"
+	| "too_many_conversations"
+	| "busy";
+
+/** What a client sends: one JSON object per WebSocket text message. */
+export type ClientFrame =
+	/** A fresh token for the same person, sent when the server asks with `reauth`. */
+	| { type: "auth"; token: string }
+	/**
+	 * A message. Without `conversation` it opens a new conversation of `persona`; `id` is the
+	 * client's own reference, echoed by `accepted` or `error`.
+	 */
+	| {
+			type: "send";
+			id: string;
+			conversation?: string;
+			persona?: string;
+			text: string;
+	  }
+	/** Stops the conversation's running turn. */
+	| { type: "stop"; conversation: string }
+	/** Approves or declines an approval prompt. */
+	| { type: "approval"; prompt: string; approved: boolean }
+	/** Answers a question prompt: the chosen options' labels and, where allowed, their own text. */
+	| { type: "answer"; prompt: string; choices: string[]; text?: string };
+
+/** What the server sends: one JSON object per WebSocket text message. */
+export type ServerFrame =
+	/** The connection is authenticated; sent first, and again after a fresh token. */
+	| {
+			type: "ready";
+			protocol: typeof WEBCHAT_PROTOCOL_VERSION;
+			speaker: { id: string; name: string; tier: Tier };
+			personas: readonly PersonaSummary[];
+			/** When the token expires, as an ISO time. */
+			expiresAt: string;
+	  }
+	/** The message `id` was taken into `conversation`, a new one when the client named none. */
+	| { type: "accepted"; id: string; conversation: string }
+	/** The assistant is, or is no longer, working in the conversation. */
+	| { type: "typing"; conversation: string; on: boolean }
+	/** A stop control applies, or no longer applies, to the conversation. */
+	| { type: "stoppable"; conversation: string; on: boolean }
+	/** What the running turn writes and which tools it runs, as it goes. */
+	| { type: "progress"; conversation: string; event: TurnProgress }
+	/** The turn's answer, in full markdown, with any files it made. */
+	| {
+			type: "reply";
+			conversation: string;
+			text: string;
+			thinking?: string;
+			files?: readonly ReplyFileFrame[];
+	  }
+	/** The turn ended without an answer: it failed, the host refused it before it ran, or it was stopped. The cause stays in the server's log. */
+	| { type: "failed"; conversation: string; stopped: boolean }
+	/** The turn asks the person; answer with `approval` or `answer`. */
+	| { type: "prompt"; conversation: string; prompt: PromptFrame }
+	| {
+			type: "prompt_closed";
+			conversation: string;
+			prompt: string;
+			outcome: PromptOutcome;
+	  }
+	/** The token expires soon: send `auth` with a fresh one before `expiresAt`, or the server closes with 4401. */
+	| { type: "reauth"; expiresAt: string }
+	/** A frame was refused; `ref` is the `send` id or prompt id it was about. */
+	| { type: "error"; code: ErrorCode; ref?: string };
+
+/** The longest client reference, conversation id, or prompt id accepted. */
+const ID_CHARS = 128;
+
+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 optional = <T>(value: unknown, check: (v: unknown) => v is T) =>
+	value === undefined || check(value);
+
+/** 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 "auth":
+			return typeof value.token === "string" && value.token !== ""
+				? { type: "auth", token: value.token }
+				: undefined;
+		case "send": {
+			const { id, conversation, persona, text } = value;
+			if (!isId(id) || typeof text !== "string") return undefined;
+			if (!optional(conversation, isId) || !optional(persona, isId))
+				return undefined;
+			if (conversation === undefined && persona === undefined) return undefined;
+			return {
+				type: "send",
+				id,
+				text,
+				...(conversation === undefined ? {} : { conversation }),
+				...(persona === undefined ? {} : { persona }),
+			};
+		}
+		case "stop":
+			return isId(value.conversation)
+				? { type: "stop", conversation: value.conversation }
+				: undefined;
+		case "approval":
+			return isId(value.prompt) && typeof value.approved === "boolean"
+				? { type: "approval", prompt: value.prompt, approved: value.approved }
+				: undefined;
+		case "answer": {
+			const { prompt, choices, text } = value;
+			if (!isId(prompt) || !Array.isArray(choices)) return undefined;
+			if (!choices.every((choice) => typeof choice === "string"))
+				return undefined;
+			if (!optional(text, (t): t is string => typeof t === "string"))
+				return undefined;
+			return {
+				type: "answer",
+				prompt,
+				choices: choices as string[],
+				...(text === undefined ? {} : { text }),
+			};
+		}
+		default:
+			return undefined;
+	}
+}

package/src/rest.ts

@@ -0,0 +1,158 @@
+import type { ConversationRecord, Logger } from "pi-roundtable";
+import { type Admitted, Refusal, type WebChat } from "./chat.ts";
+import { TokenRefused } from "./oidc.ts";
+import type { TicketBook } from "./tickets.ts";
+
+export interface RestOptions {
+	chat: WebChat;
+	tickets: TicketBook;
+	/** The route's path, such as `/chat`, without a trailing slash. */
+	path: string;
+	/** The browser origins allowed to call the API; "any" answers every origin. */
+	origins: readonly string[] | "any";
+	logger: Logger;
+}
+
+/** The most transcript entries one request returns. */
+const MAX_LIMIT = 500;
+const DEFAULT_LIMIT = 50;
+const MAX_BODY_BYTES = 16 * 1024;
+
+type HeaderMap = Record<string, string>;
+
+const json = (body: unknown, status = 200, headers: HeaderMap = {}) =>
+	Response.json(body, { status, headers });
+
+function bearer(request: Request): string | undefined {
+	const header = request.headers.get("authorization");
+	const match = header ? /^Bearer\s+(\S+)$/i.exec(header) : null;
+	return match?.[1];
+}
+
+function summary(record: ConversationRecord, surface: string) {
+	return {
+		conversation: record.key.slice(surface.length + 1),
+		persona: record.kind,
+		...(record.title === undefined ? {} : { title: record.title }),
+		createdAt: record.createdAt.toISOString(),
+		lastActiveAt: record.lastActiveAt.toISOString(),
+	};
+}
+
+async function body(request: Request): Promise<Record<string, unknown>> {
+	const text = await request.text();
+	if (text.length > MAX_BODY_BYTES) throw new Refusal("bad_frame");
+	let value: unknown;
+	try {
+		value = text === "" ? {} : JSON.parse(text);
+	} catch {
+		throw new Refusal("bad_frame");
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		throw new Refusal("bad_frame");
+	return value as Record<string, unknown>;
+}
+
+const STATUS: Record<string, number> = {
+	bad_frame: 400,
+	forbidden: 403,
+	unknown_conversation: 404,
+	unknown_persona: 404,
+	too_many_conversations: 429,
+};
+
+/**
+ * The web chat's REST API, under its path, every call with `Authorization: Bearer <token>`:
+ * `POST tickets` (a one-time ticket for the WebSocket), `GET conversations` (the caller's own),
+ * `POST conversations` (`{ persona, title? }` opens one), and `GET conversations/<id>/messages`
+ * (`?limit=`, its last messages). A browser on another origin gets CORS headers when its origin
+ * is allowed and 403 otherwise.
+ */
+export function restHandler(options: RestOptions) {
+	const { chat, tickets, path, origins, logger } = options;
+	const surface = chat.surface.surface;
+	const cors = (origin: string | null): HeaderMap | undefined => {
+		if (origin === null) return {};
+		if (origins !== "any" && !origins.includes(origin)) return undefined;
+		return { "Access-Control-Allow-Origin": origin, Vary: "Origin" };
+	};
+	async function route(
+		request: Request,
+		url: URL,
+		who: Admitted,
+		headers: HeaderMap,
+	): Promise<Response> {
+		const rest = url.pathname.slice(path.length + 1);
+		const { speaker, identity } = who;
+		if (rest === "tickets" && request.method === "POST") {
+			const { ticket, expiresAt } = tickets.issue(identity);
+			return json({ ticket, expiresAt: expiresAt.toISOString() }, 201, headers);
+		}
+		if (rest === "conversations" && request.method === "GET") {
+			const records = await chat.list(speaker);
+			return json(
+				{ conversations: records.map((r) => summary(r, surface)) },
+				200,
+				headers,
+			);
+		}
+		if (rest === "conversations" && request.method === "POST") {
+			const { persona, title } = await body(request);
+			if (typeof persona !== "string") throw new Refusal("bad_frame");
+			if (title !== undefined && typeof title !== "string")
+				throw new Refusal("bad_frame");
+			const conversation = chat.open(speaker, persona, title);
+			return json({ conversation, persona }, 201, headers);
+		}
+		const messages = /^conversations\/([A-Za-z0-9-]{1,128})\/messages$/.exec(
+			rest,
+		);
+		if (messages?.[1] && request.method === "GET") {
+			const asked = Number(url.searchParams.get("limit") ?? DEFAULT_LIMIT);
+			const limit = Number.isInteger(asked)
+				? Math.min(Math.max(asked, 1), MAX_LIMIT)
+				: DEFAULT_LIMIT;
+			const entries = await chat.transcript(speaker, messages[1], limit);
+			return json({ messages: entries }, 200, headers);
+		}
+		return json({ error: "not_found" }, 404, headers);
+	}
+	return async (request: Request): Promise<Response> => {
+		const headers = cors(request.headers.get("origin"));
+		if (!headers) return json({ error: "forbidden" }, 403);
+		if (request.method === "OPTIONS")
+			return new Response(null, {
+				status: 204,
+				headers: {
+					...headers,
+					"Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+					"Access-Control-Allow-Headers": "authorization, content-type",
+					"Access-Control-Max-Age": "600",
+				},
+			});
+		// A request the listener received always has an absolute URL.
+		const url = URL.parse(request.url);
+		if (!url) return json({ error: "not_found" }, 404, headers);
+		const token = bearer(request);
+		const challenge = { ...headers, "WWW-Authenticate": "Bearer" };
+		if (!token) return json({ error: "unauthorized" }, 401, challenge);
+		let who: Admitted;
+		try {
+			who = await chat.admit(token);
+		} catch (error) {
+			if (error instanceof TokenRefused) {
+				logger.info({ reason: error.reason }, "a web chat token was refused");
+				return json({ error: "unauthorized" }, 401, challenge);
+			}
+			if (error instanceof Refusal)
+				return json({ error: "forbidden" }, 403, headers);
+			throw error;
+		}
+		try {
+			return await route(request, url, who, headers);
+		} catch (error) {
+			if (!(error instanceof Refusal)) throw error;
+			return json({ error: error.code }, STATUS[error.code] ?? 400, headers);
+		}
+	};
+}

package/src/surface.ts

@@ -0,0 +1,126 @@
+import {
+	type ChannelKey,
+	type ChatSurface,
+	type InboundMessage,
+	type OutboundReply,
+	type OwnerPrompts,
+	PluginError,
+	parseChannelKey,
+	type Speaker,
+	type TurnProgress,
+} from "pi-roundtable";
+import type { PromptDesk } from "./prompts.ts";
+import type { ServerFrame } from "./protocol.ts";
+
+export interface WebSurfaceOptions {
+	/** The key prefix of the conversations, such as "web". */
+	surface: string;
+	/** Whose a conversation is, by its id; undefined while the process has not seen it. */
+	principalOf(conversation: string): string | undefined;
+	/** Sends a frame to every connection of a person. */
+	send(principal: string, frame: ServerFrame): void;
+	prompts: PromptDesk;
+}
+
+/**
+ * The web conversations as a chat surface: what the host shows in a conversation goes to every
+ * open connection of its person, as JSON frames. A reply is sent whole, in markdown, with its
+ * files inline.
+ */
+export class WebSurface implements ChatSurface {
+	readonly surface: string;
+	readonly supportsFiles = true;
+	readonly #options: WebSurfaceOptions;
+	#deliver: ((message: InboundMessage) => void) | undefined;
+
+	constructor(options: WebSurfaceOptions) {
+		this.surface = options.surface;
+		this.#options = options;
+	}
+
+	async start(deliver: (message: InboundMessage) => void): Promise<void> {
+		this.#deliver = deliver;
+	}
+
+	async stop(): Promise<void> {
+		this.#deliver = undefined;
+	}
+
+	/** Hands a person's message to the host; throws before the host started the surface. */
+	deliver(message: InboundMessage): void {
+		if (!this.#deliver)
+			throw new PluginError(
+				"the web chat surface has not started; messages are taken once the host runs",
+			);
+		this.#deliver(message);
+	}
+
+	/** The conversation id of a channel this surface serves. */
+	conversationOf(channel: ChannelKey): string {
+		const { surface, id } = parseChannelKey(channel);
+		if (surface !== this.surface)
+			throw new PluginError(`${channel} is not a ${this.surface} conversation`);
+		return id;
+	}
+
+	#to(channel: ChannelKey): { principal: string; conversation: string } {
+		const conversation = this.conversationOf(channel);
+		const principal = this.#options.principalOf(conversation);
+		if (!principal)
+			throw new PluginError(
+				`no one is known to own ${channel}; a web conversation is known once its person writes in it`,
+			);
+		return { principal, conversation };
+	}
+
+	async sendReply(channel: ChannelKey, reply: OutboundReply): Promise<void> {
+		const { principal, conversation } = this.#to(channel);
+		this.#options.send(principal, {
+			type: "reply",
+			conversation,
+			text: reply.chunks.join("\n"),
+			...(reply.thinking ? { thinking: reply.thinking } : {}),
+			...(reply.files?.length
+				? {
+						files: reply.files.map((file) => ({
+							name: file.name,
+							data: Buffer.from(file.data).toString("base64"),
+						})),
+					}
+				: {}),
+		});
+	}
+
+	/** A pair of frames: `on` now, and the returned function sends `off` once. */
+	#toggle(channel: ChannelKey, type: "typing" | "stoppable"): () => void {
+		const { principal, conversation } = this.#to(channel);
+		this.#options.send(principal, { type, conversation, on: true });
+		let on = true;
+		return () => {
+			if (!on) return;
+			on = false;
+			this.#options.send(principal, { type, conversation, on: false });
+		};
+	}
+
+	startTyping(channel: ChannelKey): () => void {
+		return this.#toggle(channel, "typing");
+	}
+
+	showStop(channel: ChannelKey): () => void {
+		return this.#toggle(channel, "stoppable");
+	}
+
+	/** Prompts for the conversation's own person only; a turn for anyone else asks nothing here. */
+	prompts(channel: ChannelKey, speaker?: Speaker): OwnerPrompts | undefined {
+		if (!speaker) return undefined;
+		const { principal, conversation } = this.#to(channel);
+		if (speaker.id !== principal) return undefined;
+		return this.#options.prompts.prompts(conversation, speaker);
+	}
+
+	progress(channel: ChannelKey, event: TurnProgress): void {
+		const { principal, conversation } = this.#to(channel);
+		this.#options.send(principal, { type: "progress", conversation, event });
+	}
+}