pi-roundtable-sandbox 0.24.0 → 0.24.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.24.1] - 2026-10-29
+
+### Added
+
+- `sandbox({ replyText })`: rewrites each successful model reply on the host before it is split and posted (`(text, { channel, space }) => string | Promise<string>`), for example to convert stray Simplified Chinese to Traditional. Failure texts never pass through it, the worker's history keeps the model's own words, and a throw or a non-string fails the turn like any other failure. Host-only: no worker protocol change, no image rebuild. An empty result posts nothing, as an empty model reply does.
+- `SandboxClaimOptions.reportFailure` receives the error as its second argument, and the plugin logs it with the channel.
+
 ## [0.24.0] - 2026-10-29
 
 The core peer range is now `>=0.24.0 <0.25.0`. Every new option is optional; with none set, behavior, mounts, files on disk, the worker protocol and the public API are as in 0.23.x, and `PiSandboxRuntime` is unchanged.

package/README.md

@@ -177,6 +177,14 @@ Without `budgets` and `skills`, an oversized `prompt` is still cut at 8,192 byte
 Any other cleartext URL still needs `allowHttp`, and credentials in the URL stay refused.
 This applies to `modelUrl` only, not to MCP servers.
 
+### Rewriting replies on the host
+
+`replyText(text, { channel, space })` rewrites each successful model reply on the host before it is split and posted, and may return a promise.
+Use it for what the prompt cannot guarantee, such as converting a model's stray Simplified Chinese to Traditional.
+It never sees failure texts, and the history the worker keeps holds the model's own words.
+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.
+
 ### Worker image protocol
 
 The worker image carries the label `pi-roundtable-sandbox.protocol` with the worker protocol version (2 in this release, exported as `SANDBOX_PROTOCOL`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.24.0",
+	"version": "0.24.1",
 	"description": "Sealed guest channels and an allow-listed credential broker for pi-roundtable",
 	"type": "module",
 	"license": "MIT",
@@ -52,7 +52,7 @@
 		"@biomejs/biome": "2.5.15",
 		"@types/bun": "1.4.3",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.24.0",
+		"pi-roundtable": "0.24.1",
 		"typebox": "1.3.37",
 		"typescript": "7.0.2"
 	}

package/src/claim.ts

@@ -8,13 +8,25 @@ import { splitReply } from "pi-roundtable/kit";
 import type { SandboxChannelStore } from "./channel-store.ts";
 import { type SandboxRuntime, SandboxTurnRefused } from "./runtime.ts";
 
+/**
+ * Rewrites a successful model reply before it is posted, such as converting script or stripping
+ * markup. It runs on the host, after the sealed turn and before the reply is split into chunks;
+ * failure texts never pass through it. A throw, or a value that is not a string, fails the turn.
+ */
+export type SandboxReplyText = (
+	text: string,
+	context: { channel: ChannelKey; space?: string },
+) => string | Promise<string>;
+
 export interface SandboxClaimOptions {
 	/** `owns` adds channels in configured guilds; without it only `has` decides. */
 	channels: Pick<SandboxChannelStore, "has"> &
 		Partial<Pick<SandboxChannelStore, "owns">>;
 	runtime: Pick<SandboxRuntime, "runTurn" | "stop" | "startFresh">;
 	surfaces: Pick<SurfacePort, "sendReply" | "startTyping">;
-	reportFailure?: (channel: ChannelKey) => void;
+	/** Told of a failed turn, with what failed (a sandbox error, or replyText's own throw). */
+	reportFailure?: (channel: ChannelKey, error: unknown) => void;
+	replyText?: SandboxReplyText;
 }
 
 export function isSandboxAddress(message: InboundMessage): boolean {
@@ -26,6 +38,21 @@ export function isSandboxAddress(message: InboundMessage): boolean {
 	);
 }
 
+async function rewriteReply(
+	replyText: SandboxReplyText | undefined,
+	text: string,
+	message: InboundMessage,
+): Promise<string> {
+	if (!replyText) return text;
+	const rewritten = await replyText(text, {
+		channel: message.channel,
+		...(message.space ? { space: message.space } : {}),
+	});
+	if (typeof rewritten !== "string")
+		throw new TypeError("replyText must return a string");
+	return rewritten;
+}
+
 /** 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 =>
@@ -68,15 +95,16 @@ export function sandboxClaim(options: SandboxClaimOptions): ChannelClaim {
 							text,
 							{ space: message.space },
 						);
+						const posted = reply.ok
+							? await rewriteReply(options.replyText, reply.text, message)
+							: "The sandbox turn failed.";
 						await options.surfaces.sendReply(message.channel, {
-							chunks: splitReply(
-								reply.ok ? reply.text : "The sandbox turn failed.",
-							),
+							chunks: splitReply(posted),
 						});
 					} catch (error) {
 						// A stop or a full queue is the runtime working as designed, not a failure.
 						if (!(error instanceof SandboxTurnRefused))
-							options.reportFailure?.(message.channel);
+							options.reportFailure?.(message.channel, error);
 						await options.surfaces.sendReply(message.channel, {
 							chunks: ["The sandbox turn failed or was stopped."],
 						});

package/src/index.ts

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

package/src/plugin.ts

@@ -3,7 +3,7 @@ import { dirname, isAbsolute, resolve } from "node:path";
 import { type ChannelKey, definePlugin, serviceKey } from "pi-roundtable";
 import { DISCORD } from "pi-roundtable/discord";
 import { SandboxChannelStore } from "./channel-store.ts";
-import { sandboxClaim } from "./claim.ts";
+import { type SandboxReplyText, sandboxClaim } from "./claim.ts";
 import { sandboxCommands } from "./commands.ts";
 import { SandboxRuntime, type SandboxRuntimeOptions } from "./runtime.ts";
 
@@ -23,6 +23,12 @@ export interface SandboxOptions
 	provider?: string;
 	/** Read before each model call with its channel and speaker; never falls back to the host login. */
 	apiKey?: SandboxRuntimeOptions["apiKey"];
+	/**
+	 * Rewrites each successful model reply on the host before it is posted, for example to
+	 * convert Simplified to Traditional Chinese. Failure texts are not passed to it; a throw
+	 * fails the turn.
+	 */
+	replyText?: SandboxReplyText;
 }
 export interface SandboxService {
 	channels: SandboxChannelStore;
@@ -75,10 +81,11 @@ export function sandbox(options: SandboxOptions) {
 						channels,
 						runtime,
 						surfaces: context.surfaces,
-						reportFailure: (channel) =>
+						...(options.replyText ? { replyText: options.replyText } : {}),
+						reportFailure: (channel, error) =>
 							context.logger.error(
-								{ channel },
-								"sandbox turn failed; inspect container cleanup and broker configuration",
+								{ channel, err: error },
+								"sandbox turn failed; inspect the error, then container cleanup, broker configuration and replyText",
 							),
 					}),
 				],