pi-roundtable 0.31.2 → 0.31.4

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.31.4] - 2026-11-02
+
+- Release in lockstep with pi-roundtable-web 0.31.4 (a card asked in a dispatch thread or temp knight's room shows in the room above it, in the animated scene and the chat); no core behavior changes.
+
+## [0.31.3] - 2026-11-02
+
+### Added
+
+- `DiscordCard.titleUrl`: an absolute `http` or `https` address (at most 2,048 characters, else `invalid`) the card's title links to, so a renderer passes the title as plain text in both kinds. A card with a `preview` sends it as the embed's `url` (Discord does not render Markdown in an embed title); a Components V2 card writes its heading as a Markdown link whose text is the title, with `\`, `[` and `]` in the title escaped. Non-ASCII characters are percent-encoded and so are `(` and `)`. Absent, a card is sent exactly as before.
+
+### Changed
+
+- Editing a Components V2 card with a `preview` set no longer fails: `editCard` and `editWebhookCard` send the legacy body and, when Discord refuses it as an invalid form (`rejected`, code 50035), send the card once more as Components V2 without the preview, so the message keeps its kind (a second request; if that is `rejected` too the first error is thrown, and any other failure of the retry, such as `unavailable` or `message_gone`, is thrown as it is). A preview card edited without `preview` is still `rejected`. `fakeDiscordPoster` behaves the same way. This lets a renderer set `preview` on every card edit, including for cards posted before it did.
+
 ## [0.31.2] - 2026-11-02
 
 ### Added

package/docs/plugins.md

@@ -2920,7 +2920,8 @@ The rules the poster keeps, so a plugin does not rediscover them:
 - **Nothing pings by accident.** Every post, edit, card and direct message sends `allowed_mentions` with `parse: []` and, for a post, the `mentions` users you list (at most 20). `@everyone`, roles and users merely named in the text never ping.
 - **Cards are Components V2 messages.** A card carries no `content`, so a card alone makes a blank push or desktop notification; give it a `preview` (next bullet) when that matters. Three lessons: every `editCard` re-sends the Components V2 flag (without it Discord answers a 400); a message posted by `say` cannot be edited into a card (`rejected`: delete it and post a card, which changes the message id); and a pin makes Discord post a system notice (type 6) as the bot, which `recentMessages` lists, `deleteAsBot` deletes, and nothing can edit (`rejected`, Discord's 50021), so skip it when looking for your own message.
 - **A card can carry a picture.** `thumbnail: { url, description? }` makes the heading a Section with a small picture beside it; `image: { url, description? }` puts a Media Gallery of one picture under the text sections and above the quiet last line. Both take an `https` address of at most 2,048 characters and an alt text of 1 to 1,024 characters, else `invalid`; `editCard` and `editWebhookCard` keep them when you send them again, and a card without them is sent exactly as before. Discord fetches the address itself, so it must be reachable from the internet.
-- **A card can carry a preview line for the notification.** `DiscordCard.preview` is one line of plain text (whitespace runs, line breaks included, become one space; at most 2,000 characters after that, and about 120 reads best). Discord builds a push or desktop notification from a message's `content`, which a Components V2 message cannot have, so a card with a `preview` is sent as a legacy message instead: `content` is the preview, one embed holds the card (the title; the sections joined by blank lines as the description; `accent` as the colour; `footer`; `thumbnail` and `image` as the embed's, which have no alt text, so a `description` is dropped) and `buttons`, `links` and `selects` are ordinary action rows, no Components V2 flag. It works for `sayCard`, `postCard`, `editCard`, `editWebhookCard` and a forum post's first message alike, and an edit sets `content` too. The same text guard holds (3,800 characters in all), a title is at most 256 characters, the embed's text (the sections joined by blank lines) at most 4,096, its footer at most 2,048 and the title, text and footer together at most 6,000, and a card has at most five rows (one for each menu and one for the buttons), else `invalid`. A card without `preview` is sent exactly as before. The poster cannot change a message's kind: an edit that would turn a Components V2 message into a preview card, or a preview card into Components V2, is `rejected` (delete it and post a new one, which changes the message id), so decide once per message. An edit that leaves out the buttons removes them.
+- **A card can carry a preview line for the notification.** `DiscordCard.preview` is one line of plain text (whitespace runs, line breaks included, become one space; at most 2,000 characters after that, and about 120 reads best). Discord builds a push or desktop notification from a message's `content`, which a Components V2 message cannot have, so a card with a `preview` is sent as a legacy message instead: `content` is the preview, one embed holds the card (the title; the sections joined by blank lines as the description; `accent` as the colour; `footer`; `thumbnail` and `image` as the embed's, which have no alt text, so a `description` is dropped) and `buttons`, `links` and `selects` are ordinary action rows, no Components V2 flag. It works for `sayCard`, `postCard`, `editCard`, `editWebhookCard` and a forum post's first message alike, and an edit sets `content` too. The same text guard holds (3,800 characters in all), a title is at most 256 characters, the embed's text (the sections joined by blank lines) at most 4,096, its footer at most 2,048 and the title, text and footer together at most 6,000, and a card has at most five rows (one for each menu and one for the buttons), else `invalid`. A card without `preview` is sent exactly as before. The poster cannot change a message's kind, and it does not read the message before an edit. An edit of a Components V2 card with a `preview` therefore stays a Components V2 card and the preview is left out (a Components V2 message has no `content`): the poster sends the legacy body, and when Discord refuses it as an invalid form (`rejected`, code 50035) it sends the card once more as Components V2 without `preview`; that makes a second request. When the retry is `rejected` too the first error is thrown; any other failure of the retry (`unavailable`, `forbidden`, `message_gone`) is thrown as it is. This lets one renderer always set `preview` on an edit, including for cards posted before it did. The other way is not repaired: a preview card edited without `preview` is `rejected` (delete it and post a new one, which changes the message id). An edit that leaves out the buttons removes them.
+- **A card's title can link.** `DiscordCard.titleUrl` is an absolute `http` or `https` address (at most 2,048 characters; anything else is `invalid`, before any request) that `title` links to, so `title` stays plain text in both kinds. A preview card sends it as the embed's `url`, because Discord does not render Markdown in an embed title. A Components V2 card writes its heading as a Markdown link whose text is the title (after `### `), with `\`, `[` and `]` in the title escaped (other Markdown in the title works as without `titleUrl`). The address is normalised: non-ASCII characters are percent-encoded (the host as punycode), and `(` and `)` become `%28` and `%29` so they cannot end the link. Without `titleUrl` a card is sent exactly as before; an edit without it removes the link.
 - **A webhook can post a card.** `postCard` takes the same `webhook`, `username` and `avatarUrl` as `post` plus a `card`, and sends it with `with_components=true`, which Discord allows for the bot's own (application-owned) webhooks; a button or menu on it reaches your interaction handler like one on a bot card, and the colour bar stays. `editWebhookCard(channelId, messageId, card, webhooks)` asks each named webhook in order, as `edit` does: `message_gone` when none posted it, `rejected` for a message that is not a card. The webhook's token is never logged or put in an error.
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.31.2",
+	"version": "0.31.4",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/discord/poster/poster-card-parts.ts

@@ -33,6 +33,38 @@ export function isHttps(url: string | undefined): url is string {
 	}
 }
 
+/**
+ * The checked, normalised address of a card's `titleUrl`: absolute `http` or `https`, at most 2,048
+ * characters once normalised. Non-ASCII characters are percent-encoded (the host as punycode), and
+ * so are `(` and `)`, which would end a Markdown link early.
+ */
+export function checkTitleUrl(url: string): string {
+	let href: string;
+	try {
+		const parsed = new URL(url);
+		if (
+			url !== url.trim() ||
+			!(parsed.protocol === "https:" || parsed.protocol === "http:")
+		)
+			throw new Error("not http(s)");
+		href = parsed.href.replace(/\(/g, "%28").replace(/\)/g, "%29");
+	} catch {
+		throw invalid(
+			`a card's titleUrl is an absolute http or https address of at most ${AVATAR_URL_MAX} characters`,
+		);
+	}
+	if (href.length > AVATAR_URL_MAX)
+		throw invalid(
+			`a card's titleUrl is an absolute http or https address of at most ${AVATAR_URL_MAX} characters`,
+		);
+	return href;
+}
+
+/** A card title as the label of a Markdown link: `\`, `[` and `]` escaped, so the label cannot end the link early. */
+export function linkLabel(title: string): string {
+	return title.replace(/[\\[\]]/g, "\\$&");
+}
+
 /** The checked wire form of a card's picture: an `https` address, and an alt text of 1 to 1,024 characters when given. */
 export function checkPicture(label: string, picture: CardPicture) {
 	if (!(isHttps(picture.url) && picture.url === picture.url.trim()))

package/src/core/discord/poster/poster-checks.ts

@@ -8,7 +8,9 @@ import {
 	cardRows,
 	checkCardTextSize,
 	checkPicture,
+	checkTitleUrl,
 	isHttps,
+	linkLabel,
 } from "./poster-card-parts.ts";
 import { invalid } from "./poster-errors.ts";
 import { legacyCardBody } from "./poster-legacy-card.ts";
@@ -153,7 +155,10 @@ export function checkChannelName(label: string, name: string): void {
 export function cardBody(card: DiscordCard) {
 	if (card.preview !== undefined)
 		return legacyCardBody({ ...card, preview: card.preview });
-	const heading = `### ${card.title}`;
+	const heading =
+		card.titleUrl === undefined
+			? `### ${card.title}`
+			: `### [${linkLabel(card.title)}](${checkTitleUrl(card.titleUrl)})`;
 	const main = [heading, ...card.sections.filter((section) => section !== "")];
 	const footer = card.footer ? [`-# ${card.footer}`] : [];
 	const texts = [...main, ...footer];

package/src/core/discord/poster/poster-legacy-card.ts

@@ -3,6 +3,7 @@ import {
 	cardRows,
 	checkCardTextSize,
 	checkPicture,
+	checkTitleUrl,
 } from "./poster-card-parts.ts";
 import { invalid } from "./poster-errors.ts";
 
@@ -61,6 +62,8 @@ export function legacyCardBody(card: DiscordCard & { preview: string }) {
 	const image = card.image
 		? checkPicture("a card's image", card.image)
 		: undefined;
+	const url =
+		card.titleUrl === undefined ? undefined : checkTitleUrl(card.titleUrl);
 	const components = cardRows(card);
 	if (components.length > DISCORD_LIMITS.actionRows)
 		throw invalid(
@@ -71,6 +74,7 @@ export function legacyCardBody(card: DiscordCard & { preview: string }) {
 		embeds: [
 			{
 				title: card.title,
+				...(url ? { url } : {}),
 				...(sections.length > 0 ? { description } : {}),
 				...(card.accent === undefined ? {} : { color: card.accent }),
 				...(card.footer ? { footer: { text: card.footer } } : {}),

package/src/core/discord/poster/poster.ts

@@ -109,13 +109,22 @@ export interface DiscordCard {
 	 * rows for `buttons`, `links` and `selects` (at most five rows: one per menu, one for the
 	 * buttons). An embed has no alt text, so a picture's `description` is dropped. `editCard` and
 	 * `editWebhookCard` re-send the card (and an edit sets `content` too), but the poster cannot
-	 * change a message's kind: an edit that would turn a Components V2 message into a preview card,
-	 * or the other way round, is `rejected`.
+	 * change a message's kind. An edit with a `preview` of a message that is a Components V2 card
+	 * keeps it a Components V2 card and leaves the `preview` out (the message has no `content`
+	 * to put it in); an edit without `preview` of a preview card is `rejected`.
 	 */
 	preview?: string;
 	/** The colour of the bar along the side, as 0xRRGGBB. */
 	accent?: number;
 	title: string;
+	/**
+	 * An absolute `http` or `https` address (at most 2,048 characters, else `invalid`) the title links
+	 * to, so `title` stays plain text in both kinds: the embed's `url` for a card with a `preview`
+	 * (Discord does not render Markdown in an embed title), and a masked Markdown link in
+	 * a Components V2 card's heading, with `\`, `[` and `]` in the title escaped. Non-ASCII
+	 * characters are percent-encoded and so are `(` and `)`. Absent, the title is plain text as before.
+	 */
+	titleUrl?: string;
 	sections: readonly string[];
 	/** A small picture beside the heading (a Section with a Thumbnail); the heading is the section's text. */
 	thumbnail?: CardPicture;

package/src/core/discord/poster/rest-poster.ts

@@ -1,5 +1,5 @@
 import { RESTJSONErrorCodes, Routes } from "discord.js";
-import type { DiscordPoster, PosterFile } from "./poster.ts";
+import type { DiscordCard, DiscordPoster, PosterFile } from "./poster.ts";
 import {
 	cardBody,
 	checkAvatar,
@@ -179,6 +179,36 @@ export function restPoster(
 		}
 	};
 
+	/**
+	 * Sends a card edit. A message cannot change its kind, and the poster does not read the message
+	 * first: when an edit of a card with a `preview` is `rejected` as an invalid form (Discord's 50035,
+	 * what a change of kind answers), it is sent once more as a Components V2 card without the preview
+	 * (the message was one). When that is `rejected` too the first error is thrown; any other failure
+	 * of the retry (`unavailable`, `forbidden`, `message_gone`) is thrown as it is.
+	 */
+	const keepingKind = async (
+		card: DiscordCard,
+		send: (card: DiscordCard) => Promise<void>,
+	): Promise<void> => {
+		try {
+			await send(card);
+		} catch (error) {
+			if (
+				card.preview === undefined ||
+				!(error instanceof DiscordPosterError) ||
+				error.kind !== "rejected" ||
+				error.discordCode !== 50035
+			)
+				throw error;
+			const { preview: _dropped, ...v2 } = card;
+			await send(v2).catch((retry: unknown) => {
+				throw retry instanceof DiscordPosterError && retry.kind === "rejected"
+					? error
+					: retry;
+			});
+		}
+	};
+
 	/** Asks each named webhook in turn to act on a message; the first that does it ends the search, and `message_gone` is what is left when none could. */
 	const eachWebhook = async (
 		operation: string,
@@ -272,14 +302,16 @@ export function restPoster(
 		async editWebhookCard(channelId, messageId, card, names) {
 			checkSnowflake("a channel", channelId);
 			checkSnowflake("a message", messageId);
-			const body = cardBody(card);
+			cardBody(card);
 			for (const name of names) checkWebhookName(name);
-			await eachWebhook("editing a card", channelId, names, (hook) =>
-				rest.patch(Routes.webhookMessage(hook.id, hook.token, messageId), {
-					auth: false,
-					body,
-					query: new URLSearchParams({ with_components: "true" }),
-				}),
+			await keepingKind(card, (sent) =>
+				eachWebhook("editing a card", channelId, names, (hook) =>
+					rest.patch(Routes.webhookMessage(hook.id, hook.token, messageId), {
+						auth: false,
+						body: cardBody(sent),
+						query: new URLSearchParams({ with_components: "true" }),
+					}),
+				),
 			);
 		},
 		async remove(channelId, messageId, names) {
@@ -365,23 +397,26 @@ export function restPoster(
 		async editCard(channelId, messageId, card) {
 			checkSnowflake("a channel", channelId);
 			checkSnowflake("a message", messageId);
-			const body = cardBody(card);
-			const edit = () =>
-				rest.patch(Routes.channelMessage(channelId, messageId), { body });
-			try {
-				await edit();
-			} catch (error) {
-				// A forum post's first message has the post's own id. Discord refuses its edit while the
-				// post is archived (50083), so the post is opened again and the edit sent once more.
-				if (channelId !== messageId || !isCode(error, THREAD_ARCHIVED))
-					throw failure("editing a card", error);
-				await rest
-					.patch(Routes.channel(channelId), { body: { archived: false } })
-					.then(edit)
-					.catch((again: unknown) => {
-						throw failure("editing a card", again);
-					});
-			}
+			cardBody(card);
+			await keepingKind(card, async (sent) => {
+				const body = cardBody(sent);
+				const edit = () =>
+					rest.patch(Routes.channelMessage(channelId, messageId), { body });
+				try {
+					await edit();
+				} catch (error) {
+					// A forum post's first message has the post's own id. Discord refuses its edit while the
+					// post is archived (50083), so the post is opened again and the edit sent once more.
+					if (channelId !== messageId || !isCode(error, THREAD_ARCHIVED))
+						throw failure("editing a card", error);
+					await rest
+						.patch(Routes.channel(channelId), { body: { archived: false } })
+						.then(edit)
+						.catch((again: unknown) => {
+							throw failure("editing a card", again);
+						});
+				}
+			});
 		},
 		async deleteAsBot(channelId, messageId) {
 			checkSnowflake("a channel", channelId);

package/src/core/testing/fake-poster-cards.ts

@@ -14,14 +14,20 @@ export function cardContent(card: DiscordCard): string {
 }
 
 /**
- * Refuses an edit that changes a message's kind: a Components V2 message cannot be edited into a
- * `preview` (legacy) card, and a legacy message cannot become a Components V2 card.
+ * The card a message holds after an edit. A message keeps its kind: an edit with a `preview` of a
+ * Components V2 card stays one and drops the preview (as the real poster does), and an edit
+ * without one of a preview card is refused.
  */
-export function assertSameCardKind(held: DiscordCard, edit: DiscordCard): void {
-	if ((held.preview !== undefined) !== (edit.preview !== undefined))
+export function editedCard(held: DiscordCard, edit: DiscordCard): DiscordCard {
+	if (held.preview !== undefined && edit.preview === undefined)
 		throw new DiscordPosterError(
 			"rejected",
 			"editing a card failed: the poster cannot change a message's kind, Components V2 or a preview card",
 			{ discordCode: 50035, status: 400 },
 		);
+	if (held.preview === undefined && edit.preview !== undefined) {
+		const { preview: _dropped, ...v2 } = edit;
+		return v2;
+	}
+	return edit;
 }

package/src/core/testing/fake-poster.ts

@@ -15,7 +15,7 @@ import {
 } from "../discord/poster/poster-checks.ts";
 import { DiscordPosterError } from "../discord/poster/poster-errors.ts";
 import { archivedThread } from "../discord/poster/poster-forum.ts";
-import { assertSameCardKind, cardContent } from "./fake-poster-cards.ts";
+import { cardContent, editedCard } from "./fake-poster-cards.ts";
 import type { FakeForum } from "./fake-poster-forum.ts";
 import type {
 	FakePosterChannel,
@@ -292,9 +292,8 @@ class FakePosterImpl extends FakePosterReads implements FakeDiscordPoster {
 				"editing a card failed: that message is not a card",
 				{ discordCode: 50035, status: 400 },
 			);
-		assertSameCardKind(message.card, card);
-		message.card = card;
-		message.content = cardContent(card);
+		message.card = editedCard(message.card, card);
+		message.content = cardContent(message.card);
 	}
 
 	async remove(
@@ -425,9 +424,8 @@ class FakePosterImpl extends FakePosterReads implements FakeDiscordPoster {
 				"editing a card failed: that message is not a card",
 				{ discordCode: 50035, status: 400 },
 			);
-		assertSameCardKind(message.card, card);
-		message.card = card;
-		message.content = cardContent(card);
+		message.card = editedCard(message.card, card);
+		message.content = cardContent(message.card);
 	}
 
 	async deleteAsBot(channelId: string, messageId: string): Promise<void> {