pi-roundtable-sandbox 0.26.3 → 0.27.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.27.1] - 2026-10-31
+
+- Release in lockstep with pi-roundtable 0.27.1; no package-specific behavior changes. The core peer range stays `>=0.27.0 <0.28.0`.
+
+## [0.27.0] - 2026-10-31
+
+### Added
+
+- `replyCard(text, { channel, space })`: draws a PNG card for a successful reply on the host, after `replyText` and on the text that is posted; it is set as the reply's `card`, which Discord posts before the text. `undefined` posts none; a throw or rejection is logged and the reply is posted without a card. Failure texts get no card.
+- `peerBots: true`: answers the bots the host lists under `discord.peerBots` when they mention the bot or reply to it, like a person, within the host's round cap. Off by default; `isSandboxAddress(message, peerBots?)` takes the same flag. Needs pi-roundtable with `discord.peerBots` and `answersAuthor` (`pi-roundtable/kit`): the core peer range moves with the release.
+
+### Changed
+
+- The core peer range moves to `>=0.27.0 <0.28.0`; the package imports `answersAuthor` from the 0.27 kit.
+
 ## [0.26.3] - 2026-10-30
 
 - Release in lockstep with pi-roundtable 0.26.3; no package-specific behavior changes. The core peer range stays `>=0.26.0 <0.27.0`.

package/README.md

@@ -11,7 +11,7 @@ Opt-in options (below) can also sandbox a whole Discord server, share one worksp
 
 ## Requirements
 
-- Bun 1.4.4 or later and pi-roundtable `>=0.26.0 <0.27.0`.
+- Bun 1.4.4 or later and pi-roundtable `>=0.27.0 <0.28.0`.
 - A native Linux host with a local Docker daemon and a non-root service account permitted to run Docker.
 - The worker UID/GID match that account; root workers are refused.
 - A trusted OpenAI-compatible, non-streaming Chat Completions endpoint supporting function tools and `max_tokens`.
@@ -185,6 +185,26 @@ It never sees failure texts, and the history the worker keeps holds the model's
 A throw or a value that is not a string fails the turn like any other failure, and the error is logged with the channel; an empty string posts nothing, as an empty model reply does.
 It needs no new worker image.
 
+### Reply cards
+
+`replyCard(text, { channel, space })` returns a PNG (`Uint8Array`), `undefined`, or a promise of either, and runs on the host after `replyText`, on the text that is posted.
+The card goes in the reply's `card`, which the Discord surface posts as its own message before the text.
+A throw or a rejection is logged as a warning and the reply is posted without a card; failure texts get no card.
+It needs no new worker image.
+
+```ts
+sandbox({
+	// ...
+	replyCard: async (text, { channel }) => (text.length > 40 ? await drawCard(text, channel) : undefined),
+});
+```
+
+### Answering other bots
+
+`peerBots: true` opens the sandbox channels to the bots the host lists under `discord.peerBots` (explicit user ids, no wildcard): one that mentions the bot or replies to it gets a turn like a person, within the host's round cap of bot-to-bot messages in a row (default 3, restarted by a person's message).
+It is off by default, and the host's list alone decides who; the peer's text is as untrusted as a guest's.
+The access rules still have to serve the peer's identity (`discord:<id>`).
+
 ### Channel context for guests
 
 `channelContext: true` (or the Discord plugin's `ChannelContextOptions`) is off by default.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.26.3",
+	"version": "0.27.1",
 	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -36,7 +36,7 @@
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": ">=1.0.0 <2",
-		"pi-roundtable": ">=0.26.0 <0.27.0",
+		"pi-roundtable": ">=0.27.0 <0.28.0",
 		"typebox": ">=1.3.34 <2"
 	},
 	"peerDependenciesMeta": {
@@ -52,7 +52,7 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.3",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.26.3",
+		"pi-roundtable": "0.27.1",
 		"typebox": "1.3.37",
 		"typescript": "7.0.2"
 	}

package/src/claim.ts

@@ -4,7 +4,7 @@ import type {
 	InboundMessage,
 	SurfacePort,
 } from "pi-roundtable";
-import { splitReply } from "pi-roundtable/kit";
+import { answersAuthor, splitReply } from "pi-roundtable/kit";
 import {
 	type ReadChannelContext,
 	readsChannelContext,
@@ -23,6 +23,16 @@ export type SandboxReplyText = (
 	context: { channel: ChannelKey; space?: string },
 ) => string | Promise<string>;
 
+/**
+ * Draws a PNG card for a successful reply, such as a picture that goes with its text. It runs on
+ * the host after `replyText`, on the text that is posted, and the surface posts the card before
+ * the text. Return undefined for no card; a throw or a rejection posts the reply without one.
+ */
+export type SandboxReplyCard = (
+	text: string,
+	context: { channel: ChannelKey; space?: string },
+) => Uint8Array | undefined | Promise<Uint8Array | undefined>;
+
 export interface SandboxClaimOptions {
 	/** `owns` adds channels in configured guilds; without it only `has` decides. */
 	channels: Pick<SandboxChannelStore, "has"> &
@@ -32,6 +42,15 @@ export interface SandboxClaimOptions {
 	/** Told of a failed turn, with what failed (a sandbox error, or replyText's own throw). */
 	reportFailure?: (channel: ChannelKey, error: unknown) => void;
 	replyText?: SandboxReplyText;
+	replyCard?: SandboxReplyCard;
+	/** Told when `replyCard` threw; the reply is then posted without a card. */
+	reportCardFailure?: (channel: ChannelKey, error: unknown) => void;
+	/**
+	 * Answers the bots the host lists as peers (`discord.peerBots`) when they mention the bot or
+	 * reply to it, as it answers a person; default false, so a sandbox channel stays closed to bots
+	 * even when the host answers peers elsewhere.
+	 */
+	peerBots?: boolean;
 	/**
 	 * Reads the context of the channel a message was posted in; set to opt in. It is called only for
 	 * a Discord server message, with that message, and what it returns goes before the message in
@@ -42,9 +61,12 @@ export interface SandboxClaimOptions {
 	reportContextFailure?: (channel: ChannelKey, error: unknown) => void;
 }
 
-export function isSandboxAddress(message: InboundMessage): boolean {
+export function isSandboxAddress(
+	message: InboundMessage,
+	peerBots = false,
+): boolean {
 	return (
-		!message.authorIsBot &&
+		(peerBots ? answersAuthor(message) : !message.authorIsBot) &&
 		!message.integration &&
 		!message.isDirect &&
 		(message.mentionsBot || message.repliesToBot)
@@ -84,6 +106,24 @@ async function rewriteReply(
 	return rewritten;
 }
 
+/** The card for a posted reply; none, reported, when `replyCard` throws. */
+async function cardFor(
+	options: Pick<SandboxClaimOptions, "replyCard" | "reportCardFailure">,
+	text: string,
+	message: InboundMessage,
+): Promise<Uint8Array | undefined> {
+	if (!options.replyCard) return undefined;
+	try {
+		return await options.replyCard(text, {
+			channel: message.channel,
+			...(message.space ? { space: message.space } : {}),
+		});
+	} catch (error) {
+		options.reportCardFailure?.(message.channel, error);
+		return undefined;
+	}
+}
+
 /** Outranks the agent server's priority 100; ignored messages never fall through to host agents. */
 export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 	const owns = (channel: ChannelKey, space?: string): boolean =>
@@ -102,7 +142,8 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 		postsInPlace: true,
 		owns,
 		admit: (message) => {
-			if (!admits(message) || !isSandboxAddress(message)) return undefined;
+			if (!admits(message) || !isSandboxAddress(message, options.peerBots))
+				return undefined;
 			// The router resolved the author; one the host's access rules serve no one by goes
 			// unanswered, as does a message whose author it could not resolve.
 			const { speaker } = message;
@@ -133,8 +174,12 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 						const posted = reply.ok
 							? await rewriteReply(options.replyText, reply.text, message)
 							: "The sandbox turn failed.";
+						const card = reply.ok
+							? await cardFor(options, posted, message)
+							: undefined;
 						await options.surfaces.sendReply(message.channel, {
 							chunks: splitReply(posted),
+							...(card ? { card } : {}),
 						});
 					} catch (error) {
 						// A stop or a full queue is the runtime working as designed, not a failure.

package/src/index.ts

@@ -28,6 +28,7 @@ export { SandboxChannelStore } from "./channel-store.ts";
 export {
 	isSandboxAddress,
 	type SandboxClaimOptions,
+	type SandboxReplyCard,
 	type SandboxReplyText,
 	sandboxClaim,
 } from "./claim.ts";

package/src/plugin.ts

@@ -7,7 +7,11 @@ import {
 	type SandboxChannelContext,
 } from "./channel-context.ts";
 import { SandboxChannelStore } from "./channel-store.ts";
-import { type SandboxReplyText, sandboxClaim } from "./claim.ts";
+import {
+	type SandboxReplyCard,
+	type SandboxReplyText,
+	sandboxClaim,
+} from "./claim.ts";
 import { sandboxCommands } from "./commands.ts";
 import { SandboxRuntime, type SandboxRuntimeOptions } from "./runtime.ts";
 
@@ -33,6 +37,19 @@ export interface SandboxOptions
 	 * fails the turn.
 	 */
 	replyText?: SandboxReplyText;
+	/**
+	 * Draws a PNG card for each successful reply on the host, after `replyText`, from the text that
+	 * is posted; the card is posted before the text. Return undefined for none. A throw or a
+	 * rejection is logged and the reply is posted without a card. Failure texts get no card.
+	 */
+	replyCard?: SandboxReplyCard;
+	/**
+	 * Off by default. On, the bots the host lists under `discord.peerBots` are answered like a
+	 * person when they mention the bot or reply to it, within the host's round cap; any other bot
+	 * is still ignored. The host's allowlist decides who; this only opens the sandbox channels to
+	 * them, and the peer's text is as untrusted as a guest's.
+	 */
+	peerBots?: boolean;
 	/**
 	 * Off by default. On, a turn in a Discord server channel starts with what others said in that
 	 * channel since the assistant last posted, read through the Discord plugin's `channelContext`
@@ -100,6 +117,17 @@ export function sandbox(options: SandboxOptions) {
 						runtime,
 						surfaces: context.surfaces,
 						...(options.replyText ? { replyText: options.replyText } : {}),
+						...(options.replyCard
+							? {
+									replyCard: options.replyCard,
+									reportCardFailure: (channel: ChannelKey, error: unknown) =>
+										context.logger.warn(
+											{ channel, err: error },
+											"sandbox replyCard failed; the reply is posted without a card",
+										),
+								}
+							: {}),
+						...(options.peerBots ? { peerBots: true } : {}),
 						...(contextOptions && discord
 							? {
 									channelContext: (message) =>