pi-roundtable 0.7.18 → 0.8.0

package/src/core/http/listeners.ts

@@ -1,8 +1,16 @@
 import { chmodSync } from "node:fs";
-import type { Server } from "bun";
+import type { Server, WebSocketHandler } from "bun";
 import { PluginError } from "../errors.ts";
 import type { Logger } from "../log.ts";
 import { serveUnix } from "../shared/unix-server.ts";
+import {
+	type Connection,
+	DEFAULT_MAX_BUFFERED_BYTES,
+	DEFAULT_MAX_MESSAGE_BYTES,
+	isUpgrade,
+	SocketSet,
+	type WebSocketRoute,
+} from "./websocket.ts";
 
 /** A handler a plugin attaches to one of the host's configured listeners. */
 export interface HttpRoute {
@@ -13,6 +21,11 @@ export interface HttpRoute {
 	/** Omitted: every method, for a handler that answers the rest itself. */
 	methods?: readonly string[];
 	handle(request: Request): Response | Promise<Response>;
+	/**
+	 * Takes the route's WebSocket upgrade requests (GET with `Upgrade: websocket`); every other
+	 * request still reaches `handle`.
+	 */
+	websocket?: WebSocketRoute;
 }
 
 /** Where a listener serves: a unix socket, reached from outside through a tunnel, or a TCP port. */
@@ -44,6 +57,37 @@ function overlaps(a: HttpRoute, b: HttpRoute): boolean {
 	return matches(a, pathOf(b)) || matches(b, pathOf(a));
 }
 
+/** A non-special scheme's origin, such as `chrome-extension://<id>`, which URL reports as "null". */
+const OPAQUE_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/?#@:\s]+(?::\d+)?$/;
+
+/**
+ * Whether `origin` is `scheme://host[:port]` exactly as a browser sends it: a special scheme's
+ * origin, or a non-special one in lowercase without path, query, fragment, or user.
+ */
+const isOrigin = (origin: string) => {
+	const url = URL.parse(origin);
+	if (!url) return false;
+	return url.origin === "null"
+		? OPAQUE_ORIGIN.test(origin)
+		: url.origin === origin;
+};
+
+/** Refuses a WebSocket limit that is not a positive integer, naming the route and field. */
+function validateLimits(name: string, websocket: WebSocketRoute): void {
+	const limits: [string, number | undefined][] = [
+		["maxMessageBytes", websocket.maxMessageBytes],
+		["maxBufferedBytes", websocket.maxBufferedBytes],
+		["maxConnections", websocket.maxConnections],
+		["rate.messages", websocket.rate?.messages],
+		["rate.perMs", websocket.rate?.perMs],
+	];
+	for (const [field, value] of limits)
+		if (value !== undefined && !(Number.isSafeInteger(value) && value > 0))
+			throw new PluginError(
+				`route ${name} sets websocket ${field} to ${value}, which is not a positive integer`,
+			);
+}
+
 /** Refuses routes on unknown listeners, reused names, and any request two routes could both take. */
 function validate(
 	listeners: readonly ListenerConfig[],
@@ -53,6 +97,18 @@ function validate(
 	if (ids.size !== listeners.length)
 		throw new PluginError("a listener is configured twice");
 	routes.forEach((route, index) => {
+		if (route.websocket && route.methods && !route.methods.includes("GET"))
+			throw new PluginError(
+				`route ${route.name} takes WebSockets, so its methods must include GET`,
+			);
+		if (route.websocket) validateLimits(route.name, route.websocket);
+		const { origins } = route.websocket ?? {};
+		if (origins && origins !== "any")
+			for (const origin of origins)
+				if (!isOrigin(origin))
+					throw new PluginError(
+						`route ${route.name} lists origin ${JSON.stringify(origin)}, which is not a scheme://host[:port] origin`,
+					);
 		if (!ids.has(route.listener))
 			throw new PluginError(
 				`route ${route.name} needs listener ${route.listener}, which is not configured`,
@@ -71,6 +127,16 @@ function validate(
 const serverError = () =>
 	new Response("Internal Server Error", { status: 500 });
 
+/** The route that takes a request, when one does. */
+const routeFor = (routes: readonly HttpRoute[], request: Request) => {
+	// pi-lens-ignore: unchecked-throwing-call -- the server builds request.url, always an absolute URL
+	const path = new URL(request.url).pathname;
+	return routes.find(
+		(r) =>
+			matches(r, path) && (!r.methods || r.methods.includes(request.method)),
+	);
+};
+
 /**
  * Routes one listener's request; a request no route takes is 404, and a route that throws, or
  * whose promise rejects, is 500 with a fixed body. The failure is logged with the route's name
@@ -82,12 +148,7 @@ export async function routeRequest(
 	listener: string,
 	logger: Logger,
 ): Promise<Response> {
-	// pi-lens-ignore: unchecked-throwing-call -- the server builds request.url, always an absolute URL
-	const path = new URL(request.url).pathname;
-	const route = routes.find(
-		(r) =>
-			matches(r, path) && (!r.methods || r.methods.includes(request.method)),
-	);
+	const route = routeFor(routes, request);
 	if (!route) return new Response("Not found", { status: 404 });
 	try {
 		return await route.handle(request);
@@ -97,39 +158,87 @@ export async function routeRequest(
 	}
 }
 
+/** What every request on one listener is served with. */
+interface ListenerContext {
+	listener: string;
+	logger: Logger;
+	sockets: SocketSet;
+}
+
+/**
+ * Routes one listener's request like `routeRequest`, except that a WebSocket upgrade for a route
+ * that takes them goes to its `websocket`; a failing `accept` answers and logs like a failing
+ * `handle`. Answers nothing once the socket is upgraded.
+ */
+async function serveRequest(
+	routes: readonly HttpRoute[],
+	request: Request,
+	server: Server<Connection>,
+	{ listener, logger, sockets }: ListenerContext,
+): Promise<Response | undefined> {
+	const route = routeFor(routes, request);
+	if (!route?.websocket || !isUpgrade(request))
+		return routeRequest(routes, request, listener, logger);
+	try {
+		return await sockets.upgrade(route.name, route.websocket, request, server);
+	} catch (err) {
+		logger.error({ err, route: route.name, listener }, "route failed");
+		return serverError();
+	}
+}
+
+type Fetch = (
+	request: Request,
+	server: Server<Connection>,
+) => Promise<Response | undefined>;
+
 /** Serves HTTP on a TCP port with the same idle setting as the unix sockets. */
 function serveTcp(
 	port: number,
 	hostname: string | undefined,
-	fetch: (request: Request) => Response | Promise<Response>,
-): Server<undefined> {
-	return Bun.serve({
+	fetch: Fetch,
+	websocket: WebSocketHandler<Connection> | undefined,
+): Server<Connection> {
+	const options = {
 		port,
 		...(hostname ? { hostname } : {}),
 		idleTimeout: 0,
 		fetch,
 		error: serverError,
-	});
+		...(websocket ? { websocket } : {}),
+	};
+	// SAFETY: a listener without WebSocket routes passes no handler and never upgrades.
+	return Bun.serve(
+		options as Parameters<typeof Bun.serve<Connection>>[0],
+	) as Server<Connection>;
 }
 
+/** How long a stop waits for WebSocket routes' handlers to settle before it returns anyway. */
+const CLOSE_TIMEOUT_MS = 5_000;
+
 /** The host's HTTP listeners, each serving only the routes attached to it. */
-// pi-lens-ignore: large-class — three members: validation in the constructor, start, and stop
+// pi-lens-ignore: large-class — four members: validation in the constructor, start, the WebSocket handler, and stop
 export class HttpListeners {
 	readonly #listeners: readonly ListenerConfig[];
 	readonly #routes: readonly HttpRoute[];
 	readonly #logger: Logger;
-	#servers: Server<undefined>[] = [];
+	readonly #sockets: SocketSet;
+	readonly #closeTimeoutMs: number;
+	#servers: Pick<Server<unknown>, "stop">[] = [];
 
-	/** Validates every route before any socket opens. */
+	/** Validates every route before any socket opens; `closeTimeoutMs` bounds how long a stop waits on WebSocket handlers. */
 	constructor(
 		listeners: readonly ListenerConfig[],
 		routes: readonly HttpRoute[],
 		logger: Logger,
+		options: { closeTimeoutMs?: number } = {},
 	) {
 		validate(listeners, routes);
 		this.#logger = logger;
 		this.#listeners = listeners;
 		this.#routes = routes;
+		this.#sockets = new SocketSet(logger);
+		this.#closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_TIMEOUT_MS;
 	}
 
 	/** Opens every listener; when one fails, the ones already open close again before the error is thrown. */
@@ -139,28 +248,72 @@ export class HttpListeners {
 				const routes = this.#routes.filter(
 					(route) => route.listener === listener.id,
 				);
-				const handle = (request: Request) =>
-					routeRequest(routes, request, listener.id, this.#logger);
+				const handle: Fetch = (request, server) =>
+					serveRequest(routes, request, server, {
+						listener: listener.id,
+						logger: this.#logger,
+						sockets: this.#sockets,
+					});
+				const websocket = this.#websocketHandler(listener.id, routes);
 				if ("socketPath" in listener) {
 					this.#servers.push(
-						serveUnix(listener.socketPath, handle, { error: serverError }),
+						websocket
+							? serveUnix(listener.socketPath, handle, {
+									error: serverError,
+									websocket,
+								})
+							: serveUnix(
+									listener.socketPath,
+									(request) =>
+										routeRequest(routes, request, listener.id, this.#logger),
+									{ error: serverError },
+								),
 					);
 					chmodSync(listener.socketPath, listener.mode ?? 0o660);
 				} else {
 					this.#servers.push(
-						serveTcp(listener.port, listener.hostname, handle),
+						serveTcp(listener.port, listener.hostname, handle, websocket),
 					);
 				}
 			}
 		} catch (error) {
-			this.stop();
+			void this.stop();
 			throw error;
 		}
 	}
 
-	/** Stops accepting at once and cuts open connections, such as event streams, without waiting on them. */
-	stop(): void {
+	/** The listener's WebSocket handler, sized for its largest route limits; none without WebSocket routes. */
+	#websocketHandler(
+		listener: string,
+		routes: readonly HttpRoute[],
+	): WebSocketHandler<Connection> | undefined {
+		const websockets = routes.flatMap((route) =>
+			route.websocket ? [route.websocket] : [],
+		);
+		if (websockets.length === 0) return undefined;
+		return this.#sockets.handler(listener, {
+			maxMessageBytes: Math.max(
+				...websockets.map(
+					(w) => w.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES,
+				),
+			),
+			maxBufferedBytes: Math.max(
+				...websockets.map(
+					(w) => w.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES,
+				),
+			),
+		});
+	}
+
+	/**
+	 * Stops accepting at once and cuts open connections, such as event streams, without waiting on
+	 * them. Open WebSockets get close code 1001 first, and the stop resolves once their routes'
+	 * handlers have settled, or after the close timeout.
+	 */
+	async stop(): Promise<void> {
+		this.#sockets.closeAll();
 		for (const server of this.#servers) void server.stop(true);
 		this.#servers = [];
+		await this.#sockets.drain(this.#closeTimeoutMs);
 	}
 }

package/src/core/http/websocket.ts

@@ -0,0 +1,316 @@
+import type { Server, ServerWebSocket, WebSocketHandler } from "bun";
+import type { Logger } from "../log.ts";
+
+/**
+ * What became of one `send`: written to the connection, `"queued"` behind a client that reads
+ * slower than the route sends, or `"dropped"` because the socket is closed, or because
+ * `maxBufferedBytes` were already waiting and the socket was cut for it.
+ */
+export type WebSocketSendResult = "sent" | "queued" | "dropped";
+
+/** One socket a WebSocket route accepted, with the data its `accept` gave. */
+export interface RouteSocket<Data = unknown> {
+	readonly data: Data;
+	send(message: string | Uint8Array): WebSocketSendResult;
+	close(code?: number, reason?: string): void;
+}
+
+/** What `accept` answers: the socket's data to upgrade with, or a response that refuses it. */
+export type WebSocketAccept<Data = unknown> =
+	| { data: Data; headers?: Record<string, string> }
+	| Response;
+
+/**
+ * The WebSocket half of an HTTP route. An upgrade request on the route's path passes the Origin
+ * check, then `accept`, which authenticates it before any socket opens; other requests still
+ * reach the route's `handle`.
+ */
+export interface WebSocketRoute<Data = unknown> {
+	/**
+	 * The `Origin` values a browser may connect from, each as `scheme://host[:port]` exactly as the
+	 * browser sends it, such as `https://chat.example.com` or `chrome-extension://<id>`; a request
+	 * with another Origin, or none, is refused with 403 before `accept`. `"any"` skips the check,
+	 * for clients that are not browsers.
+	 */
+	origins: readonly string[] | "any";
+	/** Authenticates and authorizes the upgrade; a thrown error answers 500 like a failing `handle`. */
+	accept(
+		request: Request,
+	): WebSocketAccept<Data> | Promise<WebSocketAccept<Data>>;
+	/**
+	 * The largest message in bytes; a larger one closes the socket with 1009. Default 64 KiB. A
+	 * message over twice the listener's largest limit drops the connection before it is read.
+	 */
+	maxMessageBytes?: number;
+	/** At most `messages` per `perMs` from one socket; one more closes it with 1008. Default 120 a minute. */
+	rate?: { messages: number; perMs: number };
+	/**
+	 * The most bytes one socket may have waiting for a client that reads slower than the route
+	 * sends. It is checked before each `send`: a `send` that finds this many waiting returns
+	 * `"dropped"` and cuts the socket without a close frame, so the client and the route's `close`
+	 * both see 1006; one that finds fewer is sent whole, so the bytes waiting can reach this limit
+	 * plus one message. Default 1 MiB.
+	 */
+	maxBufferedBytes?: number;
+	/** The most sockets the route holds open at once; another upgrade gets 503 before `accept`. Default 256. */
+	maxConnections?: number;
+	/** What a handler returns is ignored; a promise is awaited. */
+	open?(socket: RouteSocket<Data>): unknown | Promise<unknown>;
+	/** Called per message as it arrives, without waiting for the previous call to settle. */
+	message(
+		socket: RouteSocket<Data>,
+		message: string | Uint8Array,
+	): unknown | Promise<unknown>;
+	/** Called once the socket closed, also when the listener stops (code 1001); stop waits for it. */
+	close?(
+		socket: RouteSocket<Data>,
+		code: number,
+		reason: string,
+	): unknown | Promise<unknown>;
+}
+
+export const DEFAULT_MAX_MESSAGE_BYTES = 64 * 1024;
+export const DEFAULT_MAX_BUFFERED_BYTES = 1024 * 1024;
+const DEFAULT_MAX_CONNECTIONS = 256;
+const DEFAULT_RATE = { messages: 120, perMs: 60_000 };
+
+/** The close codes RFC 6455 names for the reasons this module closes a socket. */
+const GOING_AWAY = 1001;
+const POLICY_VIOLATION = 1008;
+const TOO_BIG = 1009;
+const INTERNAL_ERROR = 1011;
+
+/** What the server keeps on each socket: its route, the route's socket, and its rate window. */
+export interface Connection {
+	route: string;
+	websocket: WebSocketRoute;
+	data: unknown;
+	socket?: RouteSocket;
+	windowStart: number;
+	count: number;
+}
+
+/** Whether the request asks to become a WebSocket: a GET with `Upgrade: websocket`. */
+export const isUpgrade = (request: Request): boolean =>
+	request.method === "GET" &&
+	request.headers.get("upgrade")?.toLowerCase() === "websocket";
+
+/** Whether an upgrade request carries the key and the version 13 that RFC 6455 requires. */
+const completeHandshake = (request: Request): boolean =>
+	Boolean(request.headers.get("sec-websocket-key")) &&
+	request.headers.get("sec-websocket-version") === "13";
+
+const originAllowed = (route: WebSocketRoute, origin: string | null) =>
+	route.origins === "any" ||
+	(origin !== null && route.origins.includes(origin));
+
+const byteLength = (message: string | Uint8Array) =>
+	typeof message === "string" ? Buffer.byteLength(message) : message.byteLength;
+
+/**
+ * Sends one message unless the route's `maxBufferedBytes` already wait; then, or when Bun drops
+ * the message, the socket is cut (1006) rather than left open with a gap in what it was sent.
+ * Bun answers 0 for an empty message it did send, and for a message it dropped.
+ */
+function send(
+	ws: ServerWebSocket<Connection>,
+	message: string | Uint8Array,
+): WebSocketSendResult {
+	if (ws.readyState !== WebSocket.OPEN) return "dropped";
+	const limit =
+		ws.data.websocket.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
+	if (ws.getBufferedAmount() < limit) {
+		const status = ws.send(message);
+		if (ws.readyState !== WebSocket.OPEN) return "dropped";
+		if (status > 0 || (status === 0 && byteLength(message) === 0))
+			return "sent";
+		if (status === -1) return "queued";
+	}
+	ws.terminate();
+	return "dropped";
+}
+
+/** Resolves after `promise` settles or `ms` passes, whichever comes first. */
+async function settledWithin(promise: Promise<unknown>, ms: number) {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	await Promise.race([
+		promise,
+		new Promise<void>((resolve) => {
+			timer = setTimeout(resolve, ms);
+		}),
+	]);
+	clearTimeout(timer);
+}
+
+/**
+ * The open sockets of one host's listeners and the handler calls still running on them. A route
+ * handler that throws or rejects closes its socket with 1011 and logs the route and listener,
+ * never the URL.
+ */
+export class SocketSet {
+	readonly #open = new Set<ServerWebSocket<Connection>>();
+	readonly #running = new Set<Promise<void>>();
+	/** Each route's open sockets plus the upgrades still in `accept`. */
+	readonly #held = new Map<WebSocketRoute, number>();
+	readonly #logger: Logger;
+
+	constructor(logger: Logger) {
+		this.#logger = logger;
+	}
+
+	/**
+	 * Upgrades a request for a WebSocket route. A handshake without a key or version 13 is 400, a
+	 * refused Origin 403, and a route at `maxConnections` 503, all before `accept`; the response
+	 * `accept` returns is sent as it is, and a throwing `accept` is passed to the caller like a
+	 * failing `handle`. Answers nothing once the socket is upgraded.
+	 */
+	async upgrade(
+		name: string,
+		websocket: WebSocketRoute,
+		request: Request,
+		server: Server<Connection>,
+	): Promise<Response | undefined> {
+		if (!completeHandshake(request))
+			return new Response("Bad Request", { status: 400 });
+		if (!originAllowed(websocket, request.headers.get("origin")))
+			return new Response("Forbidden", { status: 403 });
+		const held = this.#held.get(websocket) ?? 0;
+		if (held >= (websocket.maxConnections ?? DEFAULT_MAX_CONNECTIONS))
+			return new Response("Service Unavailable", { status: 503 });
+		// The place is taken while `accept` runs, so concurrent upgrades cannot overshoot it.
+		this.#held.set(websocket, held + 1);
+		let upgraded = false;
+		try {
+			const accepted = await websocket.accept(request);
+			if (accepted instanceof Response) return accepted;
+			const connection: Connection = {
+				route: name,
+				websocket,
+				data: accepted.data,
+				windowStart: Date.now(),
+				count: 0,
+			};
+			// Bun runs `open` inside `upgrade`, and `close` releases the place from then on.
+			upgraded = server.upgrade(request, {
+				data: connection,
+				...(accepted.headers ? { headers: accepted.headers } : {}),
+			});
+			return upgraded
+				? undefined
+				: new Response("Bad Request", { status: 400 });
+		} finally {
+			if (!upgraded) this.#release(websocket);
+		}
+	}
+
+	#release(websocket: WebSocketRoute): void {
+		const held = (this.#held.get(websocket) ?? 1) - 1;
+		if (held > 0) this.#held.set(websocket, held);
+		else this.#held.delete(websocket);
+	}
+
+	/**
+	 * The Bun handler for one listener's sockets, given its largest route limits. Bun drops a frame
+	 * over twice the message limit unread; up to there each route's own limit closes with 1009.
+	 * Bun drops a message only when the largest buffered limit already waits, which each route's
+	 * `send` checks first at its own limit, so a single message larger than any limit still goes out.
+	 */
+	handler(
+		listener: string,
+		limits: { maxMessageBytes: number; maxBufferedBytes: number },
+	): WebSocketHandler<Connection> {
+		return {
+			maxPayloadLength: limits.maxMessageBytes * 2,
+			backpressureLimit: limits.maxBufferedBytes,
+			open: (ws) => {
+				this.#open.add(ws);
+				const connection = ws.data;
+				connection.socket = {
+					data: connection.data,
+					send: (message) => send(ws, message),
+					close: (code, reason) => ws.close(code, reason),
+				};
+				const { open } = connection.websocket;
+				if (open) this.#run(ws, listener, (socket) => open(socket));
+			},
+			message: (ws, message) => {
+				const connection = ws.data;
+				const { websocket } = connection;
+				const limit = websocket.maxMessageBytes ?? DEFAULT_MAX_MESSAGE_BYTES;
+				if (byteLength(message) > limit) {
+					ws.close(TOO_BIG, "message too big");
+					return;
+				}
+				const rate = websocket.rate ?? DEFAULT_RATE;
+				const now = Date.now();
+				if (now - connection.windowStart >= rate.perMs) {
+					connection.windowStart = now;
+					connection.count = 0;
+				}
+				connection.count += 1;
+				if (connection.count > rate.messages) {
+					ws.close(POLICY_VIOLATION, "too many messages");
+					return;
+				}
+				this.#run(ws, listener, (socket) => websocket.message(socket, message));
+			},
+			close: (ws, code, reason) => {
+				this.#open.delete(ws);
+				this.#release(ws.data.websocket);
+				const { close } = ws.data.websocket;
+				if (close)
+					this.#run(ws, listener, (socket) => close(socket, code, reason));
+			},
+		};
+	}
+
+	/** Runs one route handler, tracked until it settles; a failure closes the socket. */
+	#run(
+		ws: ServerWebSocket<Connection>,
+		listener: string,
+		call: (socket: RouteSocket) => unknown | Promise<unknown>,
+	): Promise<void> {
+		const connection = ws.data;
+		const running = (async () => {
+			try {
+				if (connection.socket) await call(connection.socket);
+			} catch (err) {
+				this.#logger.error(
+					{ err, route: connection.route, listener },
+					"websocket handler failed",
+				);
+				ws.close(INTERNAL_ERROR, "internal error");
+			}
+		})();
+		this.#running.add(running);
+		void running.finally(() => this.#running.delete(running));
+		return running;
+	}
+
+	/** Closes every open socket with 1001, so each route's `close` runs. */
+	closeAll(): void {
+		for (const ws of this.#open) ws.close(GOING_AWAY, "server stopping");
+	}
+
+	/**
+	 * Waits, at most `timeoutMs`, until every socket has closed and every handler call has settled;
+	 * a close the server reports later, or a call it starts meanwhile, is waited for too.
+	 */
+	async drain(timeoutMs: number): Promise<void> {
+		const deadline = Date.now() + timeoutMs;
+		while (this.#open.size > 0 || this.#running.size > 0) {
+			const left = deadline - Date.now();
+			if (left <= 0) {
+				this.#logger.warn(
+					{ open: this.#open.size, running: this.#running.size },
+					"websocket handlers still running after the close timeout",
+				);
+				return;
+			}
+			await settledWithin(
+				Promise.allSettled([...this.#running]),
+				Math.min(left, 10),
+			);
+		}
+	}
+}

package/src/core/i18n/cards.ts

@@ -11,10 +11,9 @@ export function cardsEn(ctx: CatalogContext) {
 		cardStopped: "⏹️ This round was stopped.",
 		cardExpired: "⌛ Timed out with no answer.",
 		cardOwnerOnly: `Only ${ctx.assistant}'s owner can answer this card.`,
-		cardApproversNote: (minTier: string) =>
-			`-# Who can approve: ${minTier} and above`,
-		cardApproversRefusal: (minTier: string) =>
-			`This card needs ${minTier} or above to answer.`,
+		cardApproversNote: (userId: string) => `-# Who can approve: <@${userId}>`,
+		cardApproversRefusal:
+			"This approval is for the speaker whose turn asked for it.",
 		cardAskerNote: (userId: string) => `-# Who can answer: <@${userId}>`,
 		cardAskerRefusal: "This question is for another speaker.",
 		cardInactive: `This card is no longer active (it timed out, or ${ctx.assistant} restarted); reply in text if you need to.`,
@@ -42,9 +41,8 @@ export function cardsZhTW(ctx: CatalogContext): ReturnType<typeof cardsEn> {
 		cardStopped: "⏹️ 這一輪已停止。",
 		cardExpired: "⌛ 已逾時，沒有回答。",
 		cardOwnerOnly: `只有 ${ctx.assistant} 的擁有者能回答這張卡片。`,
-		cardApproversNote: (minTier: string) => `-# 可以核准的人：${minTier} 以上`,
-		cardApproversRefusal: (minTier: string) =>
-			`這張卡片要 ${minTier} 以上才能回答。`,
+		cardApproversNote: (userId: string) => `-# 可以核准的人：<@${userId}>`,
+		cardApproversRefusal: "這張核准卡是給提出這一輪的發話者的。",
 		cardAskerNote: (userId: string) => `-# 可以回答的人：<@${userId}>`,
 		cardAskerRefusal: "這張問題是問另一位發話者的。",
 		cardInactive: `這張卡片已經失效（逾時，或 ${ctx.assistant} 重新啟動過）；需要的話直接打字回覆。`,

package/src/core/modules/memory/owner-memory.ts

@@ -47,10 +47,12 @@ export function ownerMemoryExtension(
 	ownerId: string,
 	owner: OwnerIdentity,
 	/**
-	 * The person the running turn is for, in a session that serves several. Their memory, not
-	 * the owner's, is what the turn reads and changes; without it every turn is the owner's.
+	 * The person the running turn is for, when it may be someone other than the owner. Their
+	 * memory, not the owner's, is what the turn reads and changes; without it every turn is the owner's.
 	 */
 	speaker?: () => Speaker | undefined,
+	/** Whether the tools tell the model that each speaker has a memory of their own. */
+	describesSpeakers = speaker !== undefined,
 ): ExtensionFactory {
 	const o = ownerWords(owner);
 	/** The running turn's other speaker; undefined when the owner's own memory applies. */
@@ -59,7 +61,7 @@ export function ownerMemoryExtension(
 		return current && current.id !== ownerId ? current : undefined;
 	};
 	const storeOf = () => memories.forSpeaker(other()?.id ?? ownerId);
-	const shared = speaker
+	const shared = describesSpeakers
 		? " Whoever is speaking has a memory of their own, shared by every agent; this reads and changes theirs, not someone else's."
 		: "";
 	return (pi) => {