pi-roundtable-web 0.26.0 → 0.26.1

package/src/host/forms.ts

@@ -125,6 +125,7 @@ export function checkCard(card: {
 	state?: string | undefined;
 	links?: readonly { label: string; url: string }[] | undefined;
 	buttons?: readonly HostAction[] | undefined;
+	keep?: boolean | undefined;
 }): void {
 	if (typeof card.title !== "string" || card.title.length > LIMITS.title)
 		fail(`a card's title is at most ${LIMITS.title} characters`);
@@ -134,6 +135,8 @@ export function checkCard(card: {
 		fail(`a card's tone is note, ok, warn or risk`);
 	if (card.state !== undefined && !STATES.has(card.state))
 		fail(`a card's state is open, working, done, superseded or expired`);
+	if (card.keep !== undefined && typeof card.keep !== "boolean")
+		fail("a card's keep is true or false");
 	const links = card.links ?? [];
 	if (links.length > LIMITS.links)
 		fail(`a card takes at most ${LIMITS.links} links`);

package/src/host/frames.ts

@@ -60,7 +60,7 @@ export async function actInRoom(
 	if (press.card !== undefined) {
 		const card = await ctx.cards.get(room, press.card);
 		if (!card) return { refused: "unknown" };
-		offered = buttonsFor(viewer, found, access, card);
+		offered = await buttonsFor(viewer, found, access, card);
 	} else {
 		const header = await found.kind
 			.header?.(viewer, found.id)
@@ -146,6 +146,13 @@ export function installFrames(ctx: HostContext): void {
 						connection,
 						audience: { room: frame.room },
 					});
+			// So is a turn already running: a seat at the round table shows it from the first frame, not after the next change.
+			const activity = ctx.app.activityOf(asRoom(frame.room));
+			if (activity.typing)
+				ctx.sockets.deliver(
+					{ type: "activity", room: frame.room, ...activity },
+					{ connection, audience: { room: frame.room } },
+				);
 		},
 	);
 

package/src/host/host-app.ts

@@ -19,7 +19,7 @@ import type { Uploads } from "../app/uploads.ts";
 import type { Viewer, WebAppRegistry } from "../web-app.ts";
 import { HostAccess } from "./access.ts";
 import type { HostCardLog } from "./cards.ts";
-import { hostChannelContext } from "./context.ts";
+import { type HostRoomContext, hostRoomContext } from "./context.ts";
 import { installFrames } from "./frames.ts";
 import type { HostContext } from "./host-context.ts";
 import { hostArea, pagesArea } from "./host-routes.ts";
@@ -66,7 +66,7 @@ export class HostApp {
 	readonly rooms: HostRoomsService;
 	readonly pages: HostPagesService;
 	readonly #context: HostContext;
-	readonly #channelContext: ReturnType<typeof hostChannelContext>;
+	readonly #roomContext: HostRoomContext;
 
 	constructor(options: HostAppOptions) {
 		const now = options.now ?? Date.now;
@@ -102,6 +102,8 @@ export class HostApp {
 			maxFileBytes: options.maxFileBytes,
 			roomUrl: options.roomUrl,
 			listed,
+			context: (room, contextOptions) =>
+				this.#roomContext.peek(room, contextOptions),
 			now,
 			logger: options.logger,
 		});
@@ -126,7 +128,7 @@ export class HostApp {
 			now,
 			logger: options.logger,
 		};
-		this.#channelContext = hostChannelContext(this.#context);
+		this.#roomContext = hostRoomContext(this.#context);
 	}
 
 	/** Plugs the pieces into the registry: who reads, the frames, the areas, and the services a host reaches. */
@@ -153,7 +155,7 @@ export class HostApp {
 		message: InboundMessage,
 		options?: ChannelContextOptions,
 	): Promise<ChannelContext | undefined> {
-		return this.#channelContext(message, options);
+		return this.#roomContext.read(message, options);
 	}
 
 	/** Whether a stored file bound to a room or a page may be served to this viewer now. */

package/src/host/host-routes.ts

@@ -1,4 +1,4 @@
-import type { HostCardView, RoomMessage } from "../api-types.ts";
+import type { HostCardView, RoomMessage, SendWording } from "../api-types.ts";
 import { bad, bodyOf, HttpError } from "../app/api-http.ts";
 import { PAGE_LIMIT } from "../app/room-log.ts";
 import { json } from "../http.ts";
@@ -244,14 +244,15 @@ async function open(
 		ctx.log.page(room, undefined, OPEN_LIMIT),
 		ctx.cards.list(room),
 	]);
-	const cards: HostCardView[] = stored.map((card) =>
-		cardView(viewer, found, access, card),
+	const cards: HostCardView[] = await Promise.all(
+		stored.map((card) => cardView(viewer, found, access, card)),
 	);
 	return {
 		room,
 		kind: found.kind.kind,
 		id: found.id,
 		access: { send: [...access.send], act: access.act },
+		...wordingOf(found.kind.sendWording),
 		header,
 		messages: withExpiredFiles(page.messages, ctx.files),
 		more: page.more,
@@ -261,6 +262,38 @@ async function open(
 	};
 }
 
+/** The longest label and placeholder a kind may give, in characters. */
+const LABEL_CHARS = 40;
+const PLACEHOLDER_CHARS = 100;
+
+const trimmed = (value: unknown, chars: number): string | undefined =>
+	typeof value === "string"
+		? Array.from(value.trim()).slice(0, chars).join("") || undefined
+		: undefined;
+
+/** The kind's wording of the two ways to write as the page may show it: text only, cut short; nothing when it gave none. */
+function wordingOf(wording: SendWording | undefined): {
+	wording?: SendWording;
+} {
+	const note = trimmed(wording?.note?.placeholder, PLACEHOLDER_CHARS);
+	const label = trimmed(wording?.turn?.label, LABEL_CHARS);
+	const turn = trimmed(wording?.turn?.placeholder, PLACEHOLDER_CHARS);
+	if (!note && !label && !turn) return {};
+	return {
+		wording: {
+			...(note ? { note: { placeholder: note } } : {}),
+			...(label || turn
+				? {
+						turn: {
+							...(label ? { label } : {}),
+							...(turn ? { placeholder: turn } : {}),
+						},
+					}
+				: {}),
+		},
+	};
+}
+
 async function older(
 	ctx: HostContext,
 	viewer: Viewer,

package/src/host/room-views.ts

@@ -77,27 +77,27 @@ export interface FoundRoom {
  * The buttons of a host card this viewer may press: none once the card is settled, none without
  * `access.act`, and otherwise the card's own, narrowed by the kind's `buttons` when it has one.
  */
-export function buttonsFor(
+export async function buttonsFor(
 	viewer: Viewer,
 	found: FoundRoom,
 	access: RoomAccess,
 	card: StoredHostCard,
-): NonNullable<StoredHostCard["buttons"]> {
+): Promise<NonNullable<StoredHostCard["buttons"]>> {
 	const all = card.buttons ?? [];
 	if (!access.act || !pressable(card) || all.length === 0) return [];
 	if (!found.kind.buttons) return all;
-	const allowed = new Set(found.kind.buttons(viewer, found.id, card));
+	const allowed = new Set(await found.kind.buttons(viewer, found.id, card));
 	return all.filter((button) => allowed.has(button.id));
 }
 
 /** A host card as one viewer sees it. */
-export function cardView(
+export async function cardView(
 	viewer: Viewer,
 	found: FoundRoom,
 	access: RoomAccess,
 	card: StoredHostCard,
-): HostCardView {
-	const buttons = buttonsFor(viewer, found, access, card);
+): Promise<HostCardView> {
+	const buttons = await buttonsFor(viewer, found, access, card);
 	return {
 		id: card.id,
 		room: card.room,

package/src/host/rooms-service.ts

@@ -1,5 +1,6 @@
 import type { ChannelKey, Logger } from "pi-roundtable";
 import { PluginError } from "pi-roundtable";
+import type { ChannelContext } from "pi-roundtable/discord";
 import type { ServerFrame } from "../api-types.ts";
 import { MAX_MESSAGE_CHARS } from "../api-types.ts";
 import { type FileDir, isFileId, safeName } from "../app/files.ts";
@@ -15,6 +16,7 @@ import type {
 } from "../web-app.ts";
 import type { HostAccess } from "./access.ts";
 import type { HostCardLog } from "./cards.ts";
+import type { HostRoomContextOptions } from "./context.ts";
 import { checkCard } from "./forms.ts";
 import { cardView, checkPicture, type FoundRoom } from "./room-views.ts";
 
@@ -37,6 +39,11 @@ export interface HostRoomsOptions {
 	roomUrl(room: ChannelKey, message?: number): string;
 	/** Which kinds a person's last list showed, so the list's changes reach only them. */
 	listed: ListedKinds;
+	/** A room's recent messages as a channel-context block, without marking them handed over. */
+	context(
+		room: string,
+		options?: HostRoomContextOptions,
+	): Promise<ChannelContext | undefined>;
 	now?: () => number;
 	logger: Logger;
 }
@@ -272,6 +279,14 @@ export class HostRoomsService implements HostRooms {
 		return this.#options.log.byReference(room, reference);
 	}
 
+	async context(
+		room: ChannelKey,
+		options?: HostRoomContextOptions,
+	): Promise<ChannelContext | undefined> {
+		this.#found(room);
+		return this.#options.context(room, options);
+	}
+
 	// ── Cards ──
 
 	async card(room: ChannelKey, card: HostCard): Promise<{ id: string }> {
@@ -313,7 +328,7 @@ export class HostRoomsService implements HostRooms {
 					{
 						type: "host_card",
 						room,
-						card: cardView(viewer, found, access, stored),
+						card: await cardView(viewer, found, access, stored),
 					},
 					{ connection, audience: { room } },
 				);

package/src/host/views.ts

@@ -8,6 +8,7 @@ import type {
 	PictureRef,
 	ReadMarkView,
 	RoomMessage,
+	SendWording,
 } from "../api-types.ts";
 
 /** One room of a kind, as the list shows it. */
@@ -47,6 +48,8 @@ export interface HostRoomView {
 	id: string;
 	/** What this viewer may do in the room. */
 	access: { send: ("note" | "turn")[]; act: boolean };
+	/** The kind's own wording of the two ways to write, where it gave any. */
+	wording?: SendWording;
 	header: HostHeaderView;
 	/** The newest messages, oldest first. */
 	messages: RoomMessage[];

package/src/i18n/zh-tw.ts

@@ -288,6 +288,7 @@ export const ZH_TW: Readonly<Record<string, string>> = {
 	"Leave the table": "離席",
 	"{name} left the table": "{name}已離席",
 	"The table is empty": "圓桌空了",
+	"There are no rooms to seat yet.": "還沒有可以入座的聊天室。",
 	"Every agent has left the table. Choose who sits down.":
 		"所有夥伴都離席了。選擇誰要上桌。",
 	"An agent who leaves the table is muted: its room stops pushing to you. A card that waits for you is always pushed.":
@@ -580,6 +581,8 @@ export const ZH_TW: Readonly<Record<string, string>> = {
 	"{count} cards waiting": "{count} 張卡片等待中",
 	"{count} finished thread": "{count} 個已結束的討論串",
 	"{count} finished threads": "{count} 個已結束的討論串",
+	"Clear all": "清除全部",
+	"The thread is still open.": "這個討論串還在進行中。",
 
 	// 排程
 	"{days} at {time}": "每{days} {time}",
@@ -1050,8 +1053,12 @@ export const ZH_TW: Readonly<Record<string, string>> = {
 	"This page is not available.": "這個頁面無法使用。",
 	"You can read this room but not write in it.":
 		"你可以閱讀這個聊天室，但不能在其中發言。",
-	"Send as": "傳送方式",
-	"Ask the agent": "請夥伴處理",
+	"@AI": "@AI",
+	"The message starts with @AI, so the agent answers.":
+		"訊息開頭是 @AI，所以 AI 會回覆。",
+	"Write an internal note…": "寫一則內部備註…",
+	"Ask AI…": "問 AI…",
+	"Internal note": "內部備註",
 	"Earlier cards ({count})": "先前的卡片（{count}）",
 	Replaced: "已被取代",
 	Image: "圖片",

package/src/index.ts

@@ -12,6 +12,7 @@ export type {
 	ConversationView,
 	DashboardView,
 	GroupView,
+	HostIconName,
 	NoteInput,
 	NoteKind,
 	NoteView,
@@ -26,7 +27,7 @@ export type {
 	TranscriptRole,
 	TranscriptView,
 } from "./api-types.ts";
-export { PANES } from "./api-types.ts";
+export { HOST_ICONS, PANES } from "./api-types.ts";
 export type { CloudflareAccessOptions } from "./cloudflare-access.ts";
 export {
 	cloudflareAccess,
@@ -39,4 +40,17 @@ export type { WebAuthOptions, WebConsoleOptions } from "./options.ts";
 export { DEFAULT_RELAY_NOTE } from "./options.ts";
 export type { RequestVerifier, Verdict } from "./verifier.ts";
 export { admit, admitAs, refuse } from "./verifier.ts";
+export type {
+	ActionResult,
+	HostCard,
+	HostPage,
+	HostRoomKind,
+	LinkProver,
+	Notices,
+	OnboardingStep,
+	OpenTarget,
+	Viewer,
+	WebApp,
+} from "./web-app.ts";
+export { WEB_APP } from "./web-app.ts";
 export { webConsole } from "./web-plugin.ts";

package/src/options.ts

@@ -116,6 +116,14 @@ export interface OidcOptions {
 	reauthHours?: number;
 	/** The id_token claims to keep with the session (replaced at each sign-in and re-verify, never logged); default none. */
 	storeClaims?: readonly string[];
+	/**
+	 * Called with the person's principal id when a request or an open socket proves they hold a
+	 * live session, at most once per session every five minutes. For a host that counts who is
+	 * present, such as one that keeps a linked chat account only while its web person is active: a
+	 * person who only has the app open, calling nothing of the host's, still counts. It is not
+	 * awaited, and an error it throws is logged and never fails the request.
+	 */
+	onSessionVerified?: (principalId: string) => void | Promise<void>;
 }
 
 /** `auth` checked and filled in. */
@@ -145,6 +153,9 @@ export interface ResolvedOidc {
 	endSession: boolean;
 	reauthHours: number | undefined;
 	storeClaims: readonly string[];
+	onSessionVerified:
+		| ((principalId: string) => void | Promise<void>)
+		| undefined;
 }
 
 /** The panes each tier is served, when the list differs by tier. */
@@ -331,6 +342,11 @@ export interface WebConsoleOptions {
 	uploads?: { keepDays?: number };
 	/** The page's title and heading; default `Roundtable`. */
 	title?: string;
+	/**
+	 * The page's description for search results and link previews (`description` and
+	 * `og:description`); default a line derived from the title.
+	 */
+	description?: string;
 	/** Where the install icons come from; default the ones this package ships. */
 	icons?: { dir: string };
 	/** How the page looks: `modern` (default) or `camelot`. The page's owner can switch it in the app. */
@@ -397,6 +413,7 @@ export interface ResolvedOptions {
 	modes: boolean;
 	uploadKeepDays: number;
 	title: string;
+	description: string | undefined;
 	iconsDir: string | undefined;
 	look: "modern" | "camelot";
 	relayNotes: readonly string[];
@@ -546,6 +563,11 @@ function checkPanes(
 					`${label} names the ${pane} pane, which the owners' panes do not have; the pane's API is served for the owners' list`,
 				);
 		}
+		// A member's table seats the host rooms they may list, which the rooms pane brings with its socket.
+		if (list.includes("table") && !list.includes("rooms"))
+			fail(
+				`${label} names the table pane without the rooms pane, whose host rooms it seats`,
+			);
 	}
 	return { owner, admin, member, given: true };
 }
@@ -704,6 +726,7 @@ function checkOidc(auth: OidcOptions): ResolvedOidc {
 		"endSession",
 		"reauthHours",
 		"storeClaims",
+		"onSessionVerified",
 	]);
 	for (const key of Object.keys(auth))
 		if (!known.has(key)) fail(`auth.${key} is not an oidc option`);
@@ -778,6 +801,11 @@ function checkOidc(auth: OidcOptions): ResolvedOidc {
 		!storeClaims.every((name) => typeof name === "string" && name.trim())
 	)
 		fail("auth.storeClaims must be a list of claim names");
+	if (
+		auth.onSessionVerified !== undefined &&
+		typeof auth.onSessionVerified !== "function"
+	)
+		fail("auth.onSessionVerified must be a function");
 	return {
 		mode: "oidc",
 		issuer,
@@ -798,6 +826,7 @@ function checkOidc(auth: OidcOptions): ResolvedOidc {
 		endSession: auth.endSession === true,
 		reauthHours: auth.reauthHours,
 		storeClaims: [...storeClaims],
+		onSessionVerified: auth.onSessionVerified,
 	};
 }
 
@@ -1028,6 +1057,12 @@ export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
 		fail("appearance.look must be modern or camelot");
 	const title = options.title?.trim() ?? "Roundtable";
 	if (!title) fail("title is empty");
+	const description = options.description?.trim();
+	if (
+		options.description !== undefined &&
+		(typeof options.description !== "string" || !description)
+	)
+		fail("description is empty. Leave it out for the default");
 	return {
 		auth,
 		origin,
@@ -1050,6 +1085,7 @@ export function resolveOptions(options: WebConsoleOptions): ResolvedOptions {
 		modes: options.modes !== false,
 		uploadKeepDays: checkUploads(options),
 		title,
+		description,
 		iconsDir: options.icons?.dir,
 		look,
 		relayNotes: options.relayNotes ?? [DEFAULT_RELAY_NOTE],

package/src/page-presentation.ts

@@ -2,7 +2,7 @@ import type { ConsolePresentation } from "./features.ts";
 import { escapeHtml } from "./http.ts";
 import { PAGE_COLORS } from "./page-colors.ts";
 
-/** The tags that make the page installable; the URLs resolve against the page, so the mount does not matter. */
+/** The tags that make the page installable; their URLs resolve against the base, so they follow it. */
 const pwaTags = (look: "modern" | "camelot"): string =>
 	'<link rel="manifest" href="./manifest.webmanifest" crossorigin="use-credentials">' +
 	`<meta name="theme-color" content="${PAGE_COLORS[look].light}" media="(prefers-color-scheme: light)">` +
@@ -10,21 +10,66 @@ const pwaTags = (look: "modern" | "camelot"): string =>
 	'<link rel="apple-touch-icon" href="./icons/apple-180.png">' +
 	'<meta name="apple-mobile-web-app-capable" content="yes">';
 
+/**
+ * The icon links of a page served under `mount`: the round-table mark as an SVG when the icon
+ * directory has one, and the 192 px PNG every icon directory has (the manifest names it). Without
+ * them a browser asks the site root for `/favicon.ico`, which is not this app's.
+ */
+export const iconLinks = (mount: string, svg: boolean): string => {
+	const base = escapeHtml(mount);
+	const mark = svg
+		? `<link rel="icon" href="${base}/icons/mark.svg" type="image/svg+xml" sizes="any">`
+		: "";
+	return `${mark}<link rel="icon" href="${base}/icons/192.png" type="image/png">`;
+};
+
+/** What a page says about itself to a tab, a search result and a link preview. */
+export interface PageMeta {
+	title: string;
+	description: string;
+	/** The console's origin, so `og:image` is an absolute URL. */
+	origin: string;
+	/** The path the console is served under. */
+	mount: string;
+	/** Whether the icon directory has `mark.svg`. */
+	svg: boolean;
+}
+
+/** The text a host that sets no `description` gets. */
+export const defaultDescription = (title: string): string =>
+	`Chat with your agent team in ${title}.`;
+
+const metaTags = (meta: PageMeta): string =>
+	`<meta name="description" content="${escapeHtml(meta.description)}">` +
+	`<meta property="og:title" content="${escapeHtml(meta.title)}">` +
+	`<meta property="og:description" content="${escapeHtml(meta.description)}">` +
+	`<meta property="og:image" content="${escapeHtml(`${meta.origin}${meta.mount}/icons/512.png`)}">`;
+
 /** Authenticated, inert bootstrap data localizes even a failed first API request without inline scripts. */
 export function presentPage(
 	body: Uint8Array,
 	mount: string | undefined,
 	presentation: ConsolePresentation | undefined,
 	look: "modern" | "camelot" = "modern",
+	meta?: PageMeta,
 ): Uint8Array<ArrayBuffer> | string {
 	// Not in web/index.html: the bundler would try to resolve and rewrite these URLs.
-	let head = `<head>${pwaTags(look)}`;
+	// The base comes first: under path routing a relative link before it resolves against a deep URL.
+	let head = "<head>";
 	if (mount) head += `<base href="${escapeHtml(`${mount}/`)}">`;
+	head += pwaTags(look);
+	if (meta) head += iconLinks(meta.mount, meta.svg) + metaTags(meta);
 	if (presentation)
 		head += `<meta name="roundtable-console-presentation" content="${escapeHtml(JSON.stringify(presentation))}">`;
 	// After the base, so it resolves under the mount; a script of the page's own origin, which its policy allows.
 	head += '<script src="./theme-init.js"></script>';
 	let html = new TextDecoder().decode(body).replace("<head>", () => head);
+	// web/index.html ships a placeholder: the page is not rendered until the bundle sets the title.
+	if (meta)
+		html = html.replace(
+			/<title>[^<]*<\/title>/,
+			() => `<title>${escapeHtml(meta.title)}</title>`,
+		);
 	if (presentation?.locale)
 		html = html.replace(
 			/(<html[^>]*lang=")[^"]*(")/,

package/src/pwa.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AssetBundle } from "./assets.ts";
@@ -34,7 +34,27 @@ export const DEFAULT_ICONS_DIR = fileURLToPath(
 	new URL("../assets/icons/", import.meta.url),
 );
 
-const ICON_FILE = /^[A-Za-z0-9-]+\.png$/;
+const ICON_FILE = /^[A-Za-z0-9-]+\.(png|svg)$/;
+
+/** The icon files the page, the manifest and the sign-in pages link. */
+const PUBLIC_ICONS: ReadonlySet<string> = new Set([
+	"192.png",
+	"512.png",
+	"maskable-512.png",
+	"apple-180.png",
+	"badge-96.png",
+	"mark.svg",
+	"mark-maskable.svg",
+]);
+
+/** The manifest and the linked icons answer without a session: a sign-in page and a link preview have none. Any other file of a host's icon directory stays behind it. */
+export const isPublicStatic = (rest: string): boolean =>
+	rest === "manifest.webmanifest" ||
+	(rest.startsWith("icons/") && PUBLIC_ICONS.has(rest.slice("icons/".length)));
+
+/** Whether the icon directory has the round-table mark as an SVG, which a tab shows crisper than a PNG. */
+export const hasMarkSvg = (iconsDir: string | undefined): boolean =>
+	existsSync(join(iconsDir ?? DEFAULT_ICONS_DIR, "mark.svg"));
 
 export interface PwaOptions {
 	mount: string;
@@ -116,10 +136,18 @@ export function servePwa(
 			const body = readFileSync(
 				join(options.iconsDir ?? DEFAULT_ICONS_DIR, name),
 			);
+			const svg = name.endsWith(".svg");
 			return new Response(new Uint8Array(body), {
 				headers: {
-					"content-type": "image/png",
-					"cache-control": "private, max-age=86400",
+					"content-type": svg ? "image/svg+xml" : "image/png",
+					"cache-control": "public, max-age=86400",
+					// An SVG opened as a page must not run anything of its own.
+					...(svg
+						? {
+								"content-security-policy":
+									"default-src 'none'; style-src 'unsafe-inline'",
+							}
+						: {}),
 				},
 			});
 		} catch {

package/src/web-app.ts

@@ -1,16 +1,24 @@
 import type { ChannelKey, ServiceKey, Tier } from "pi-roundtable";
 import { PluginError, serviceKey } from "pi-roundtable";
+import type { ChannelContext } from "pi-roundtable/discord";
 import type {
 	FormFieldView,
 	FormSpecView,
 	HostActionView,
 	HostAuthorKind,
+	HostIconName,
 	PictureRef,
 	RoomFile,
+	SendWording,
 } from "./api-types.ts";
+import { HOST_ICONS } from "./api-types.ts";
 import type { Visitor } from "./visitors.ts";
 
-export type { HostAuthorKind, PictureRef };
+export type { HostAuthorKind, HostIconName, PictureRef, SendWording };
+
+/** A host's icon name as the page may show it: one of `HOST_ICONS`, else none (the default shows). */
+export const hostIcon = (name: unknown): HostIconName | undefined =>
+	HOST_ICONS.find((icon) => icon === name);
 
 /**
  * Who a host plugin's callbacks serve: the person behind a request or a socket frame, with the
@@ -104,6 +112,15 @@ export interface RoomHeader {
 export interface HostRoomKind {
 	kind: string;
 	label: string;
+	/** An icon of the console's own set, shown beside the kind's section; none = no icon. */
+	icon?: HostIconName;
+	/**
+	 * The kind's own words for writing in its rooms. Where a viewer may send both a note and a turn,
+	 * the room shows one toggle, "@AI" (off = a note for the room's people only, on =
+	 * the agent answers): `turn.label` words the toggle, and each mode's `placeholder` is the box's
+	 * hint while that mode is on. Without it the console's own words show.
+	 */
+	sendWording?: SendWording;
 	/** Rooms this viewer may open. Undefined = the kind is not shown to them. */
 	list(
 		viewer: Viewer,
@@ -129,7 +146,11 @@ export interface HostRoomKind {
 		input: FormValues,
 	): Promise<ActionResult>;
 	/** The buttons of a HOST card this viewer may press; default all when `access.act`. Never applies to held-call or question cards. */
-	buttons?(viewer: Viewer, id: string, card: StoredHostCard): readonly string[];
+	buttons?(
+		viewer: Viewer,
+		id: string,
+		card: StoredHostCard,
+	): readonly string[] | Promise<readonly string[]>;
 	/** How long the kind's messages, author names, host cards and files are kept. Unset = keep. */
 	retention?: { textDays: number; fileDays: number };
 }
@@ -143,6 +164,12 @@ export interface HostCard {
 	/** `https` or same-origin only. */
 	links?: readonly { label: string; url: string }[];
 	buttons?: readonly HostAction[];
+	/**
+	 * Keeps the card past its kind's `retention.textDays`, for as long as the host passes `true`: a
+	 * ticket's pinned card while the ticket is open. The sweep skips it; `updateCard` without `keep`
+	 * (or with `false`) makes it an ordinary card again, counted from when it was first posted.
+	 */
+	keep?: boolean;
 }
 
 /** A host card as it is stored. */
@@ -197,6 +224,17 @@ export interface HostRooms {
 	/** Deletes the row and its files now. */
 	remove(room: ChannelKey, id: number): Promise<void>;
 	byReference(room: ChannelKey, reference: string): Promise<number | undefined>;
+	/**
+	 * A room's recent messages as the block `CHANNEL_CONTEXT.read` gives a turn: what was said
+	 * since the assistant last posted, at most `limit` (default 15, at most 100) newest messages,
+	 * an outsider's words marked `external`, notices left out. For a host that starts a turn from
+	 * a room's `send` hook and has no message that addressed the assistant. Unlike `read` it marks
+	 * nothing handed over, so a retry gets the same; undefined when the room has nothing to give.
+	 */
+	context(
+		room: ChannelKey,
+		options?: { limit?: number; messageChars?: number },
+	): Promise<ChannelContext | undefined>;
 	card(room: ChannelKey, card: HostCard): Promise<{ id: string }>;
 	updateCard(room: ChannelKey, id: string, card: HostCard): Promise<void>;
 	saveFile(
@@ -237,6 +275,8 @@ export interface HostPage {
 	/** `[a-z0-9-]{1,40}`. */
 	id: string;
 	label: string;
+	/** An icon of the console's own set, shown in the navigation; none = a list. */
+	icon?: HostIconName;
 	place: "main" | "settings" | "hidden";
 	visible(viewer: Viewer): boolean | Promise<boolean>;
 	view(
@@ -255,7 +295,11 @@ export interface HostPage {
 /** Person-addressed notices with state: the bell, the badge, push. */
 export interface Notices {
 	raise(notice: {
-		/** The dedupe key: raising it again updates it and pushes again. */
+		/**
+		 * The dedupe key: raising it again updates it and pushes again. It is also the push tag
+		 * and the acknowledgement key, so the people the notice is for can see it: put no private
+		 * id in it.
+		 */
 		tag: string;
 		/** Principal ids. */
 		to: readonly string[];