pi-roundtable-webchat 0.8.0 → 0.9.0

package/src/connections.ts

@@ -35,7 +35,7 @@ export class Connections {
 
 	/** Takes a place for an upgrade that is about to open; false when the person holds every place. */
 	reserve(connection: Connection): boolean {
-		const id = connection.identity.id;
+		const id = connection.speaker.principalId;
 		const held = this.#held.get(id) ?? 0;
 		if (held >= this.#perPrincipal) return false;
 		this.#held.set(id, held + 1);
@@ -53,7 +53,7 @@ export class Connections {
 		clearTimeout(connection.pending);
 		connection.pending = undefined;
 		connection.socket = socket;
-		const id = connection.identity.id;
+		const id = connection.speaker.principalId;
 		const set = this.#byPrincipal.get(id) ?? new Set();
 		set.add(connection);
 		this.#byPrincipal.set(id, set);
@@ -63,7 +63,7 @@ export class Connections {
 	closed(connection: Connection): void {
 		for (const timer of connection.timers) clearTimeout(timer);
 		connection.timers = [];
-		const id = connection.identity.id;
+		const id = connection.speaker.principalId;
 		const set = this.#byPrincipal.get(id);
 		set?.delete(connection);
 		if (set?.size === 0) this.#byPrincipal.delete(id);
@@ -75,7 +75,7 @@ export class Connections {
 		connection.pending = undefined;
 		if (!connection.holding) return;
 		connection.holding = false;
-		const id = connection.identity.id;
+		const id = connection.speaker.principalId;
 		const held = (this.#held.get(id) ?? 1) - 1;
 		if (held > 0) this.#held.set(id, held);
 		else this.#held.delete(id);

package/src/direct-channel.ts

@@ -0,0 +1,66 @@
+import {
+	type ConversationRegistry,
+	channelKey,
+	type DirectChannelProvider,
+	type IdentityService,
+} from "pi-roundtable";
+import { Refusal, type WebChat } from "./chat.ts";
+import type { PgNotices } from "./notices.ts";
+
+export interface WebDirectChannelOptions {
+	chat: WebChat;
+	identity(): IdentityService;
+	registry(): ConversationRegistry;
+	notices: PgNotices;
+}
+
+/** A private inbox, known offline through a same-surface identity or private conversation. */
+export function webDirectChannel(
+	options: WebDirectChannelOptions,
+): DirectChannelProvider {
+	const { chat, identity, registry, notices } = options;
+	const surface = chat.surface.surface;
+	const knows = async (principalId: string) => {
+		const principal = await identity().principal(principalId);
+		if (!principal || principal.disabled) return false;
+		const linked = await identity().identities(principalId);
+		// OIDC links carry an issuer, not a chat surface. They alone cannot prove
+		// membership in this inbox: another webchat might use that same issuer.
+		if (linked.some((link) => link.provider === surface)) return true;
+		return (await registry().list({ principal: principalId })).some(
+			(record) => record.surface === surface && record.visibility === "private",
+		);
+	};
+	return {
+		name: `webchat:${surface}`,
+		label: "a notice in the web inbox",
+		knows,
+		reaches: async (principalId) => {
+			if (!(await knows(principalId))) return undefined;
+			const speaker = await identity().speakerFor(principalId);
+			const available = chat.personasFor(speaker);
+			const persona = available[0];
+			if (!persona) return undefined;
+			const records = await chat.list(speaker);
+			const existing = records.find((record) =>
+				available.some((p) => p.kind === record.kind),
+			);
+			const key = existing?.key ?? channelKey(surface, crypto.randomUUID());
+			if (!existing)
+				await registry().register({
+					key,
+					kind: persona.kind,
+					visibility: "private",
+					principalId,
+				});
+			// Proves ownership, teaches the surface the recipient, and never changes visibility.
+			await chat.own(speaker, chat.surface.conversationOf(key));
+			return key;
+		},
+		deliver: async (principalId, text) => {
+			if (!(await knows(principalId))) throw new Refusal("forbidden");
+			const notice = await notices.add(principalId, text);
+			chat.connections.sendTo(principalId, { type: "notice", notice });
+		},
+	};
+}

package/src/index.ts

@@ -1,12 +1,12 @@
-export type { WebAccess, WebAccessMap, WebTierMembers } from "./access.ts";
-export { webAccess } from "./access.ts";
 export type { WebChatLimits, WebPersona } from "./chat.ts";
+export type { Notice } from "./notices.ts";
 export type {
 	OidcJwtVerifierOptions,
 	TokenVerifier,
 	WebIdentity,
 } from "./oidc.ts";
 export {
+	identityActor,
 	oidcJwtVerifier,
 	oidcSpeakerId,
 	parseOidcSpeakerId,

package/src/notices.ts

@@ -0,0 +1,131 @@
+import type { SQL } from "bun";
+import type { Migration } from "pi-roundtable";
+
+/** A private inbox entry, independent of conversation transcripts. */
+export interface Notice {
+	id: string;
+	text: string;
+	createdAt: string;
+	readAt: string | null;
+}
+
+interface Row {
+	id: string;
+	text: string;
+	created_at: Date;
+	read_at: Date | null;
+}
+
+const noticeOf = (row: Row): Notice => ({
+	id: row.id,
+	text: row.text,
+	createdAt: row.created_at.toISOString(),
+	readAt: row.read_at?.toISOString() ?? null,
+});
+
+export interface NoticeLimits {
+	messageChars?: number;
+	maxBufferedBytes?: number;
+	/** Inbox namespace; default web, matching the plugin's default surface. */
+	surface?: string;
+}
+
+/** Fixed retention and text caps bound storage and REST response sizes. */
+export const MAX_NOTICES = 100;
+const MAX_NOTICE_CHARS = 4096;
+// ASCII UUID and timestamps plus JSON field names fit within this reserve.
+const FRAME_OVERHEAD = 256;
+
+/** The first `length` UTF-16 units of `text`, one shorter when that would split a surrogate pair. */
+const cut = (text: string, length: number): string => {
+	const last = text.charCodeAt(length - 1);
+	return text.slice(0, last >= 0xd800 && last <= 0xdbff ? length - 1 : length);
+};
+
+/** Notices scoped by surface and principal in every query, including marking one read. */
+export class PgNotices {
+	readonly #sql: SQL;
+	readonly #textChars: number;
+	readonly #surface: string;
+
+	constructor(sql: SQL, limits: NoticeLimits = {}) {
+		this.#sql = sql;
+		this.#surface = limits.surface ?? "web";
+		const bytes = limits.maxBufferedBytes ?? 4 * 1024 * 1024;
+		const chars = limits.messageChars ?? 32_000;
+		if (!Number.isSafeInteger(bytes) || bytes < FRAME_OVERHEAD + 6)
+			throw new Error(
+				"webChat: maxBufferedBytes must be an integer of at least 262 bytes to carry a notice frame",
+			);
+		if (!Number.isSafeInteger(chars) || chars < 1)
+			throw new Error("webChat: messageChars must be a positive integer");
+		// One UTF-16 unit costs at most six bytes after JSON escaping, including
+		// control characters and lone surrogates. Reserve space for the envelope.
+		this.#textChars = Math.min(
+			chars,
+			MAX_NOTICE_CHARS,
+			Math.floor((bytes - FRAME_OVERHEAD) / 6),
+		);
+	}
+
+	static readonly migration: Migration = {
+		name: "notices",
+		up: async (sql) => {
+			await sql`CREATE TABLE IF NOT EXISTS webchat_notices (
+				surface TEXT NOT NULL, principal_id TEXT NOT NULL, id UUID PRIMARY KEY, text TEXT NOT NULL,
+				created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), read_at TIMESTAMPTZ
+			)`;
+			await sql`CREATE INDEX IF NOT EXISTS webchat_notices_surface_principal_created
+				ON webchat_notices (surface, principal_id, created_at DESC, id)`;
+		},
+	};
+
+	async add(principalId: string, text: string): Promise<Notice> {
+		// A cut between a surrogate pair would store U+FFFD, so it moves before the pair.
+		const bounded =
+			text.length > this.#textChars
+				? `${cut(text, this.#textChars - 1)}…`
+				: text;
+		return this.#sql.begin(async (sql) => {
+			// Serialize insert/prune for one inbox even across pools/processes.
+			await sql`SELECT pg_advisory_xact_lock(hashtextextended(${`webchat-notices:${this.#surface}:${principalId}`}, 0))`;
+			const rows: Row[] =
+				await sql`INSERT INTO webchat_notices (surface, principal_id, id, text, created_at)
+				VALUES (${this.#surface}, ${principalId}, ${crypto.randomUUID()}, ${bounded}, clock_timestamp()) RETURNING *`;
+			if (!rows[0]) throw new Error("webchat notice insert returned no row");
+			await sql`DELETE FROM webchat_notices WHERE surface = ${this.#surface} AND principal_id = ${principalId} AND id IN (
+				SELECT id FROM webchat_notices WHERE surface = ${this.#surface} AND principal_id = ${principalId}
+				ORDER BY created_at DESC, id DESC OFFSET ${MAX_NOTICES}
+			)`;
+			return noticeOf(rows[0]);
+		});
+	}
+
+	/** Latest entries, with a bounded page; before is the last id of the previous page. */
+	async list(
+		principalId: string,
+		limit = 50,
+		before?: string,
+	): Promise<Notice[]> {
+		limit = Number.isInteger(limit)
+			? Math.min(Math.max(limit, 1), MAX_NOTICES)
+			: 50;
+		const rows: Row[] = before
+			? await this
+					.#sql`SELECT id, text, created_at, read_at FROM webchat_notices
+				WHERE surface = ${this.#surface} AND principal_id = ${principalId} AND (created_at, id) < (
+					SELECT created_at, id FROM webchat_notices WHERE id = ${before}::uuid AND surface = ${this.#surface} AND principal_id = ${principalId}
+				) ORDER BY created_at DESC, id DESC LIMIT ${limit}`
+			: await this
+					.#sql`SELECT id, text, created_at, read_at FROM webchat_notices
+				WHERE surface = ${this.#surface} AND principal_id = ${principalId} ORDER BY created_at DESC, id DESC LIMIT ${limit}`;
+		return rows.map(noticeOf);
+	}
+
+	async read(principalId: string, id: string): Promise<Notice | undefined> {
+		const rows: Row[] = await this
+			.#sql`UPDATE webchat_notices SET read_at = COALESCE(read_at, NOW())
+			WHERE surface = ${this.#surface} AND principal_id = ${principalId} AND id = ${id}::uuid RETURNING *`;
+		return rows[0] ? noticeOf(rows[0]) : undefined;
+	}
+}

package/src/oidc.ts

@@ -5,9 +5,12 @@ import {
 	type JWTVerifyGetKey,
 	jwtVerify,
 } from "jose";
+import type { ActorFacts } from "pi-roundtable";
 
 /** Who a verified token names, and until when it may be trusted. */
 export interface WebIdentity {
+	/** Verified actor facts for core; provider must start with `oidc:` or equal this chat's surface. */
+	actor?: ActorFacts;
 	/** The speaker id: reversible and unique across issuers, such as `oidc:<base64url(issuer)>:<sub>`. */
 	id: string;
 	/** How the person is shown, from the token's name claim. */
@@ -59,6 +62,35 @@ export function parseOidcSpeakerId(
 	return { issuer, subject };
 }
 
+/** Core facts for a verified identity, with roles scoped to this chat's surface. */
+export function identityActor(
+	identity: WebIdentity,
+	surface = "web",
+): ActorFacts {
+	const provider = identity.actor?.provider;
+	if (
+		provider !== undefined &&
+		!provider.startsWith("oidc:") &&
+		provider !== surface
+	)
+		throw new TokenRefused(
+			`custom actor provider must start with "oidc:" or equal this webchat surface ${JSON.stringify(surface)}`,
+		);
+	const oidc = parseOidcSpeakerId(identity.id);
+	return {
+		...(identity.actor ?? {
+			provider: oidc
+				? `oidc:${Buffer.from(oidc.issuer).toString("base64url")}`
+				: surface,
+			subject: oidc?.subject ?? identity.id,
+			legacyId: identity.id,
+		}),
+		name: identity.name,
+		surface,
+		roles: identity.roles.map((role) => `${surface}:role:${role}`),
+	};
+}
+
 export interface OidcJwtVerifierOptions {
 	/** The provider's published signing keys (`jwks_uri`): https, or http on a loopback address. */
 	jwksUrl: string;
@@ -225,12 +257,23 @@ export function oidcJwtVerifier(
 			text(options.nameClaim ? claims[options.nameClaim] : claims.name) ??
 			text(claims.preferred_username) ??
 			subject;
+		const issuer = speakerIssuer ?? (claims.iss as string);
+		const id = oidcSpeakerId(issuer, subject);
+		const roleNames = Array.isArray(roles)
+			? roles.filter((role): role is string => typeof role === "string")
+			: [];
 		return {
-			id: oidcSpeakerId(speakerIssuer ?? (claims.iss as string), subject),
+			actor: {
+				provider: `oidc:${Buffer.from(issuer).toString("base64url")}`,
+				subject,
+				name,
+				surface: "web",
+				legacyId: id,
+				roles: roleNames.map((role) => `web:role:${role}`),
+			},
+			id,
 			name,
-			roles: Array.isArray(roles)
-				? roles.filter((role): role is string => typeof role === "string")
-				: [],
+			roles: roleNames,
 			expiresAt: new Date((claims.exp as number) * 1000),
 		};
 	};

package/src/plugin.ts

@@ -2,13 +2,13 @@ import {
 	CONVERSATIONS,
 	definePlugin,
 	type HttpRoute,
+	IDENTITY,
 	type PluginContext,
 	type RoundtablePlugin,
 	RUNTIME,
 	type WebSocketAccept,
 	type WebSocketRoute,
 } from "pi-roundtable";
-import { type WebAccess, type WebAccessMap, webAccess } from "./access.ts";
 import {
 	type Admitted,
 	checkPersonas,
@@ -18,6 +18,8 @@ import {
 	type WebPersona,
 } from "./chat.ts";
 import type { Connection } from "./connections.ts";
+import { webDirectChannel } from "./direct-channel.ts";
+import { PgNotices } from "./notices.ts";
 import { TokenRefused, type TokenVerifier } from "./oidc.ts";
 import { TICKET_PROTOCOL_PREFIX, WEBCHAT_PROTOCOL } from "./protocol.ts";
 import { restHandler } from "./rest.ts";
@@ -40,8 +42,6 @@ export interface WebChatRouteLimits {
 export interface WebChatOptions {
 	/** Checks each bearer token, such as `oidcJwtVerifier({ ... })`. */
 	verifier: TokenVerifier;
-	/** Who may chat and at which tier: an access map, or `webAccess(map)`. */
-	access: WebAccessMap | WebAccess;
 	/** The conversation kinds a person may open. */
 	personas: readonly WebPersona[];
 	/**
@@ -75,13 +75,14 @@ const DEFAULT_LIMITS: WebChatLimits & WebChatRouteLimits = {
 	ticketTtlMs: 30_000,
 };
 
-const isAccess = (access: WebAccessMap | WebAccess): access is WebAccess =>
-	typeof (access as WebAccess).tierOf === "function";
-
 function checkOptions(options: WebChatOptions): {
 	path: string;
 	surface: string;
 } {
+	if ("access" in options)
+		throw new Error(
+			'webChat: access was removed; use top-level access on RoundtableConfig: members/admins roles become "<surface>:role:<role>", users become identities, and owners become access.owners[].identities. Replace everyone: true with everyone: ["<surface>"] (substitute this chat\'s surface, default "web"); core everyone: true opens every surface.',
+		);
 	const path = options.path ?? "/chat";
 	if (!/^\/[A-Za-z0-9._~/-]*[A-Za-z0-9._~-]$/.test(path))
 		throw new Error(
@@ -119,19 +120,17 @@ function offered(request: Request): string[] {
 export function webChat(options: WebChatOptions): RoundtablePlugin {
 	const { path, surface } = checkOptions(options);
 	const limits = { ...DEFAULT_LIMITS, ...options.limits };
-	const access = isAccess(options.access)
-		? options.access
-		: webAccess(options.access);
 	// The personas are checked now, so a broken list stops the configuration rather than the boot.
 	checkPersonas(options.personas);
 	return definePlugin({
 		name: surface === "web" ? "webchat" : `webchat-${surface}`,
-		requires: [CONVERSATIONS, RUNTIME],
+		requires: [IDENTITY, CONVERSATIONS, RUNTIME],
+		migrations: [PgNotices.migration],
 		setup: (context: PluginContext) => {
 			const chat = new WebChat({
 				surface,
 				verifier: options.verifier,
-				access,
+				identity: () => context.services.get(IDENTITY),
 				personas: options.personas,
 				limits,
 				logger: context.logger,
@@ -145,8 +144,10 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 				ttlMs: limits.ticketTtlMs,
 				perPrincipal: limits.connectionsPerPrincipal,
 			});
+			const notices = new PgNotices(context.database(), { ...limits, surface });
 			const rest = restHandler({
 				chat,
+				notices,
 				tickets,
 				path,
 				origins: options.origins,
@@ -172,9 +173,11 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 				try {
 					if (token) admitted = await chat.admit(token);
 					else if (ticket) {
-						const identity = tickets.redeem(ticket);
-						if (!identity) return refuse(401, "Unauthorized");
-						admitted = chat.admitIdentity(identity);
+						const held = tickets.redeem(ticket);
+						if (!held) return refuse(401, "Unauthorized");
+						admitted = await chat.admitIdentity(held.identity);
+						if (admitted.speaker.principalId !== held.principalId)
+							return refuse(403, "Forbidden");
 					} else return refuse(401, "Unauthorized");
 				} catch (error) {
 					if (error instanceof TokenRefused) {
@@ -216,6 +219,14 @@ export function webChat(options: WebChatOptions): RoundtablePlugin {
 			return {
 				surfaces: [chat.surface],
 				channels: [chat.claim()],
+				directChannels: [
+					webDirectChannel({
+						chat,
+						notices,
+						identity: () => context.services.get(IDENTITY),
+						registry: () => context.services.get(CONVERSATIONS),
+					}),
+				],
 				personas: chat.contributedPersonas,
 				http: [route],
 			};

package/src/prompts.ts

@@ -1,9 +1,9 @@
 import {
 	type Approval,
 	type OwnerAnswer,
-	type OwnerPrompts,
 	type OwnerQuestion,
-	type Speaker,
+	type PromptScope,
+	type Prompts,
 	TIERS,
 	type Tier,
 } from "pi-roundtable";
@@ -16,7 +16,7 @@ import type {
 
 /** Who answers: the conversation's person, at their tier as of the answer. */
 export interface Answerer {
-	id: string;
+	principalId: string;
 	tier: Tier;
 }
 
@@ -54,17 +54,17 @@ export class PromptDesk {
 	}
 
 	/**
-	 * 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.
+	 * The prompts of a conversation for the scope's 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 {
+	prompts(conversation: string, scope: PromptScope): Prompts {
 		return {
 			confirm: async (title, message, signal, minTier = "owner") => {
-				if (!atLeast(speaker.tier, minTier)) return "expired";
+				if (!atLeast(scope.tier, minTier)) return "expired";
 				const outcome = await this.#ask(
 					conversation,
-					speaker.id,
+					scope.principalId,
 					(id) => ({ id, kind: "approval", title, message }),
 					signal,
 					minTier,
@@ -74,7 +74,7 @@ export class PromptDesk {
 			ask: async (title, question, signal) => {
 				const { outcome, answer } = await this.#ask(
 					conversation,
-					speaker.id,
+					scope.principalId,
 					(id) => questionFrame(id, title, question),
 					signal,
 				);
@@ -102,7 +102,7 @@ export class PromptDesk {
 	): 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.principal !== from.principalId) return "forbidden";
 		if (open.minTier && !atLeast(from.tier, open.minTier)) return "forbidden";
 		open.settle(approved ? "approved" : "declined");
 		return undefined;
@@ -116,7 +116,7 @@ export class PromptDesk {
 	): ErrorCode | undefined {
 		const open = this.#open.get(prompt);
 		if (open?.frame.kind !== "ask") return "unknown_prompt";
-		if (open.principal !== from.id) return "forbidden";
+		if (open.principal !== from.principalId) return "forbidden";
 		if (!fits(open.frame, answer)) return "bad_frame";
 		open.settle("answered", answer);
 		return undefined;

package/src/protocol.ts

@@ -1,4 +1,5 @@
 import type { AskOption, Tier, TurnProgress } from "pi-roundtable";
+import type { Notice } from "./notices.ts";
 
 /**
  * The WebSocket subprotocol a client offers, and the server echoes, for this version of the
@@ -94,7 +95,7 @@ export type ServerFrame =
 	| {
 			type: "ready";
 			protocol: typeof WEBCHAT_PROTOCOL_VERSION;
-			speaker: { id: string; name: string; tier: Tier };
+			speaker: { id: string; name: string; tier: Tier; principalId: string };
 			personas: readonly PersonaSummary[];
 			/** When the token expires, as an ISO time. */
 			expiresAt: string;
@@ -125,6 +126,8 @@ export type ServerFrame =
 			prompt: string;
 			outcome: PromptOutcome;
 	  }
+	/** A durable private inbox entry; fetch the REST inbox to recover missed notices. */
+	| { type: "notice"; notice: Notice }
 	/** 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. */

package/src/rest.ts

@@ -1,11 +1,13 @@
 import type { ConversationRecord, Logger } from "pi-roundtable";
 import { type Admitted, Refusal, type WebChat } from "./chat.ts";
+import { MAX_NOTICES, type PgNotices } from "./notices.ts";
 import { TokenRefused } from "./oidc.ts";
 import type { TicketBook } from "./tickets.ts";
 
 export interface RestOptions {
 	chat: WebChat;
 	tickets: TicketBook;
+	notices: PgNotices;
 	/** 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. */
@@ -17,6 +19,7 @@ export interface RestOptions {
 const MAX_LIMIT = 500;
 const DEFAULT_LIMIT = 50;
 const MAX_BODY_BYTES = 16 * 1024;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 type HeaderMap = Record<string, string>;
 
@@ -69,7 +72,7 @@ const STATUS: Record<string, number> = {
  * is allowed and 403 otherwise.
  */
 export function restHandler(options: RestOptions) {
-	const { chat, tickets, path, origins, logger } = options;
+	const { chat, tickets, notices, path, origins, logger } = options;
 	const surface = chat.surface.surface;
 	const cors = (origin: string | null): HeaderMap | undefined => {
 		if (origin === null) return {};
@@ -85,9 +88,34 @@ export function restHandler(options: RestOptions) {
 		const rest = url.pathname.slice(path.length + 1);
 		const { speaker, identity } = who;
 		if (rest === "tickets" && request.method === "POST") {
-			const { ticket, expiresAt } = tickets.issue(identity);
+			const { ticket, expiresAt } = tickets.issue(
+				identity,
+				speaker.principalId,
+			);
 			return json({ ticket, expiresAt: expiresAt.toISOString() }, 201, headers);
 		}
+		if (rest === "notices" && request.method === "GET") {
+			const before = url.searchParams.get("before") ?? undefined;
+			if (before !== undefined && !UUID.test(before))
+				throw new Refusal("bad_frame");
+			const asked = Number(url.searchParams.get("limit") ?? DEFAULT_LIMIT);
+			const limit = Number.isInteger(asked)
+				? Math.min(Math.max(asked, 1), MAX_NOTICES)
+				: DEFAULT_LIMIT;
+			return json(
+				{ notices: await notices.list(speaker.principalId, limit, before) },
+				200,
+				headers,
+			);
+		}
+		const readNotice = /^notices\/([^/]+)\/read$/.exec(rest);
+		if (readNotice?.[1] && request.method === "POST") {
+			if (!UUID.test(readNotice[1])) throw new Refusal("bad_frame");
+			const notice = await notices.read(speaker.principalId, readNotice[1]);
+			return notice
+				? json({ notice }, 200, headers)
+				: json({ error: "not_found" }, 404, headers);
+		}
 		if (rest === "conversations" && request.method === "GET") {
 			const records = await chat.list(speaker);
 			return json(

package/src/surface.ts

@@ -3,10 +3,10 @@ import {
 	type ChatSurface,
 	type InboundMessage,
 	type OutboundReply,
-	type OwnerPrompts,
 	PluginError,
+	type PromptScope,
+	type Prompts,
 	parseChannelKey,
-	type Speaker,
 	type TurnProgress,
 } from "pi-roundtable";
 import type { PromptDesk } from "./prompts.ts";
@@ -111,12 +111,16 @@ export class WebSurface implements ChatSurface {
 		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;
+	/**
+	 * Prompts for the conversation's own person only; a turn for anyone else asks nothing here.
+	 * Its owners are not on the web chat, so a prompt above the person's tier goes to no one,
+	 * whatever the scope escalates to.
+	 */
+	prompts(channel: ChannelKey, scope?: PromptScope): Prompts | undefined {
+		if (!scope) return undefined;
 		const { principal, conversation } = this.#to(channel);
-		if (speaker.id !== principal) return undefined;
-		return this.#options.prompts.prompts(conversation, speaker);
+		if (scope.principalId !== principal) return undefined;
+		return this.#options.prompts.prompts(conversation, scope);
 	}
 
 	progress(channel: ChannelKey, event: TurnProgress): void {