pi-roundtable 0.7.2 → 0.7.4

package/CHANGELOG.md

@@ -5,6 +5,35 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-10-03
+
+### Added
+
+- Export `scrubDiagnostic` from the kit: mask credentials in subprocess or worker text (URL userinfo, bearer values, well-known token shapes, secret-named assignments), drop control characters and bound the length, so a host can show a failure's reason without its secrets.
+- Coding: `toolText` for the repository tools' descriptions and argument descriptions, `presentation.list` for the `repo_list` result, and `repo_push` takes a 7–40 character sha prefix of the reported commit.
+- Sandbox: `SandboxResearchWorker` accepts the host's own `tools` (extension packages and factories, active tool names, prompt), a `scope` around the session and the `aborted` wording.
+- Drawing: `cardPresentation.result` words the card draw result, and `mapLimits` lets a host accept longer relationship-map text.
+- Web: a channel Discord cannot name shows the `channel name unavailable` text.
+
+### Changed
+
+- Coding: git and gh failures name their scrubbed stderr again, a worker's own error reaches the report (scrubbed and bounded), the timeout and stop texts read as before ("the worker ran out of time (N minutes)", "the worker was stopped"), the refusals for a busy repository, a missing or over-long task and a full channel say what is wrong, a declined call is no longer listed as held, and the service reports the channels it works for so a shutdown can name them.
+- Sandbox: `ScopedSandboxDelegator` refuses with the reasons the core delegator gave ("title and task are required", the task length, the channel's running count), no longer limits the title, and reports a failed job's scrubbed error message or "the worker ran out of time" instead of "Sandbox task failed".
+
+## [0.7.3] - 2026-10-03
+
+### Fixed
+
+- The sandbox's rich broker streams model responses instead of buffering them and no longer cuts calls at 60 or 120 seconds; the turn deadline is the bound. The worker can no longer raise effort or thinking budget above the host-judged level. `startFresh` and start replace guest-planted symlinks instead of following them, and only the two reserved blocks of the 192.0 range are refused, not all of it.
+
+### Added
+
+- Sandbox `assertPublicUrl`, `safeFetch` options `followRedirects` and `headers`, and a research-worker `fetchContent` hook, so a host can keep a library's own extractors while its fetches of a model-supplied URL stay pinned and vetted per hop. Broker upstream errors keep their status, body and back-off headers.
+- Coding accepts `pushHoldText` for trusted wording of the held `repo_push` approval card.
+- Export `withReplyFiles` for standalone workers to collect reply attachments with the same turn-wide limits, success/failure semantics, and asynchronous scope as host conversation turns.
+- Export `prepareImageBytes` and `ImagePreparationError` from the kit for raster bytes without reopening guest-writable paths; reject encoded images over 25 MiB or headers/aggregate frames over 64 MP before native decode, while preserving ordinary 48 MP images and 9000×1 downscaling. File-based preparation is byte-bounded too and decodes once instead of twice.
+- Drawing accepts `CardPresentation` through `DrawingOptions.cardPresentation` for trusted operator headings and reversal suffixes without changing tool arguments or default captions.
+
 ## [0.7.2] - 2026-10-02
 
 ### Fixed

package/docs/plugins.md

@@ -55,6 +55,11 @@ Import fixtures and fake threads from `pi-roundtable/testing` for tests.
 Use the kit's building blocks for a plugin that runs Pi itself, such as a coding worker:
 
 - MCP: `mcpExtension` and `VirtualServer` expose MCP servers to a session, and `mcpAdapterExtension` and `readAttachmentExtension` do the same inside an out-of-process worker.
+- Admitted media: `prepareImageBytes(data, contentType)` prepares raster bytes without reopening a guest-writable path; supported small images remain unchanged, and larger sides/encoded images are downsized to JPEG at a 2,000 px long side.
+  Before any native decoder, it refuses more than 25 MiB of encoded bytes or 64 million decoded pixels, including aggregate GIF/WebP frame dimensions.
+  `ImagePreparationError.reason` is `byte-limit`, `pixel-limit`, or `invalid-image`; hosts can localize refusals without parsing native decoder errors.
+  Ordinary 48 MP images and thin 9000×1 images remain admitted.
+  This helper is not a downloader or filesystem validator.
 - Work: `promptSlot` (how a run asks the owner while it works), `workTimeout` (a time limit that does not count the time spent waiting on the owner), `runWorkerTask`, `archiveSessions`, and `approvalCard` and `canonicalJson` for the cards of held actions.
 - Shell: `SHELL_TOOLS` and `shellHoldRule`, the hold rule that keeps risky host-shell commands behind the owner's approval.
 - Tools: `textToolsExtension`, `requiredString`, `stringList` (with `toolText` and `toolError`) for tools that return text.
@@ -429,6 +434,9 @@ A Pi package should use the host's peer dependency on `pi-roundtable`, not bundl
 Transient `SessionContext.runTask` tasks return only text and cannot attach to their parent's reply.
 Calling the helper outside `context.turns.run` or an agent-team turn, or after that turn finishes, throws `ReplyFileError`; direct standalone runtime calls have no reply collector.
 Await work that produces files before returning from the tool.
+A standalone isolated worker may wrap its complete awaited turn in `withReplyFiles(supported, run)` from the main entry.
+`run` returns `Promise<TurnResult>`; the collector validates any returned files, includes accepted attachments only on success, and deactivates on success, failure, or throw.
+The caller must deliver the returned `files` and must not open a fresh collector per tool to evade turn-wide limits.
 
 | Case | Behavior |
 |---|---|
@@ -2479,6 +2487,10 @@ Import from the entries listed below; source area files are internal.
 | `TurnSelection` | `pi-roundtable` | type |
 | `Weekday` | `pi-roundtable` | type |
 | `attachReplyFile` | `pi-roundtable` | value |
+| `withReplyFiles` | `pi-roundtable` | value |
+| `prepareImageBytes` | `pi-roundtable/kit` | value |
+| `ImagePreparationError` | `pi-roundtable/kit` | value |
+| `scrubDiagnostic` | `pi-roundtable/kit` | value |
 | `channelKey` | `pi-roundtable` | value |
 | `definePlugin` | `pi-roundtable` | value |
 | `defineRoundtable` | `pi-roundtable` | value |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.7.2",
+	"version": "0.7.4",
 	"description": "A plugin-driven Pi agent server for Discord",
 	"type": "module",
 	"license": "MIT",

package/src/core/attachments/image-budget.ts

@@ -0,0 +1,158 @@
+import { ImagePreparationError } from "./image-preparation-error.ts";
+
+const invalid = () => new ImagePreparationError("invalid-image");
+
+/** Inspect only encoded headers/blocks. Never allocate a raster or follow a media URL. */
+export function assertImagePixelBudget(bytes: Buffer, budget: number): void {
+	const pixels = (width: number, height: number): number => {
+		if (width < 1 || height < 1) throw invalid();
+		const area = width * height;
+		check(area);
+		return area;
+	};
+	const check = (area: number) => {
+		if (area > budget) throw new ImagePreparationError("pixel-limit");
+	};
+	const need = (end: number, limit = bytes.length) => {
+		if (end > limit) throw invalid();
+	};
+	const u24 = (at: number) => bytes.readUIntLE(at, 3);
+	const blockEnd = (start: number): number => {
+		let at = start;
+		for (;;) {
+			need(at + 1);
+			const length = bytes[at++] ?? 0;
+			if (!length) return at;
+			at += length;
+			need(at);
+		}
+	};
+
+	if (
+		bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+	) {
+		need(24);
+		if (
+			bytes.readUInt32BE(8) !== 13 ||
+			bytes.toString("ascii", 12, 16) !== "IHDR"
+		)
+			throw invalid();
+		pixels(bytes.readUInt32BE(16), bytes.readUInt32BE(20));
+		return;
+	}
+	if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+		let at = 2;
+		while (at < bytes.length) {
+			if (bytes[at++] !== 0xff) throw invalid();
+			while (bytes[at] === 0xff) at++;
+			need(at + 1);
+			const marker = bytes[at++] ?? 0;
+			if (marker === 0xda || marker === 0xd9) break;
+			if (marker === 1 || marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7))
+				continue;
+			need(at + 2);
+			const length = bytes.readUInt16BE(at);
+			if (length < 2) throw invalid();
+			need(at + length);
+			if (
+				marker >= 0xc0 &&
+				marker <= 0xcf &&
+				![0xc4, 0xc8, 0xcc].includes(marker)
+			) {
+				if (length < 8) throw invalid();
+				pixels(bytes.readUInt16BE(at + 5), bytes.readUInt16BE(at + 3));
+				return;
+			}
+			at += length;
+		}
+		throw invalid();
+	}
+	if (["GIF87a", "GIF89a"].includes(bytes.toString("ascii", 0, 6))) {
+		need(13);
+		pixels(bytes.readUInt16LE(6), bytes.readUInt16LE(8));
+		let at =
+			13 + ((bytes[10] ?? 0) & 0x80 ? 3 * (2 << ((bytes[10] ?? 0) & 7)) : 0);
+		let total = 0;
+		need(at);
+		while (at < bytes.length) {
+			const marker = bytes[at++];
+			if (marker === 0x3b) {
+				if (!total) throw invalid();
+				return;
+			}
+			if (marker === 0x21) {
+				need(at + 1);
+				at = blockEnd(at + 1);
+				continue;
+			}
+			if (marker !== 0x2c) throw invalid();
+			need(at + 9);
+			total += pixels(bytes.readUInt16LE(at + 4), bytes.readUInt16LE(at + 6));
+			check(total);
+			const flags = bytes[at + 8] ?? 0;
+			at += 9 + (flags & 0x80 ? 3 * (2 << (flags & 7)) : 0);
+			need(at + 1);
+			at = blockEnd(at + 1);
+		}
+		throw invalid();
+	}
+	if (
+		bytes.toString("ascii", 0, 4) === "RIFF" &&
+		bytes.toString("ascii", 8, 12) === "WEBP"
+	) {
+		need(12);
+		const end = bytes.readUInt32LE(4) + 8;
+		need(end);
+		if (end < 12) throw invalid();
+		const chunks = (start: number, limit: number, frames: boolean): number => {
+			let at = start,
+				canvas = 0,
+				total = 0;
+			while (at < limit) {
+				need(at + 8, limit);
+				const type = bytes.toString("ascii", at, at + 4);
+				const size = bytes.readUInt32LE(at + 4);
+				const data = at + 8,
+					next = data + size;
+				need(next, limit);
+				let area = 0;
+				if (type === "VP8X") {
+					need(data + 10, next);
+					canvas = pixels(u24(data + 4) + 1, u24(data + 7) + 1);
+				} else if (type === "VP8 ") {
+					need(data + 10, next);
+					if (
+						!bytes
+							.subarray(data + 3, data + 6)
+							.equals(Buffer.from([0x9d, 0x01, 0x2a]))
+					)
+						throw invalid();
+					area = pixels(
+						bytes.readUInt16LE(data + 6) & 0x3fff,
+						bytes.readUInt16LE(data + 8) & 0x3fff,
+					);
+				} else if (type === "VP8L") {
+					need(data + 5, next);
+					if (bytes[data] !== 0x2f) throw invalid();
+					const bits = bytes.readUInt32LE(data + 1);
+					area = pixels((bits & 0x3fff) + 1, ((bits >>> 14) & 0x3fff) + 1);
+				} else if (type === "ANMF") {
+					if (!frames) throw invalid();
+					need(data + 16, next);
+					const declared = pixels(u24(data + 6) + 1, u24(data + 9) + 1);
+					area = Math.max(declared, chunks(data + 16, next, false));
+				}
+				total += area;
+				check(Math.max(total, canvas));
+				at = next + (size & 1);
+				need(at, limit);
+			}
+			const result = Math.max(total, canvas);
+			if (!result) throw invalid();
+			return result;
+		};
+		chunks(12, end, true);
+		return;
+	}
+	throw invalid();
+}

package/src/core/attachments/image-prep.ts

@@ -1,5 +1,8 @@
 import { createCanvas, loadImage } from "canvas";
 import type { ModelImage, StoredAttachment } from "../domain/attachment.ts";
+import { MAX_ATTACHMENT_BYTES } from "./attachment-fetcher.ts";
+import { assertImagePixelBudget } from "./image-budget.ts";
+import { ImagePreparationError } from "./image-preparation-error.ts";
 
 /** Images the model accepts as images; other files stay files. */
 const IMAGE_TYPES = new Set([
@@ -29,15 +32,41 @@ export function isModelImage(
 export async function prepareImage(
 	file: Pick<StoredAttachment, "path" | "contentType">,
 ): Promise<ModelImage> {
-	const bytes = Buffer.from(await Bun.file(file.path).arrayBuffer());
-	const mimeType = file.contentType.split(";")[0]?.trim().toLowerCase() ?? "";
-	if (bytes.byteLength <= MAX_RAW_BYTES) {
-		const image = await loadImage(bytes);
-		if (Math.max(image.width, image.height) <= MAX_SIDE) {
-			return { data: bytes.toString("base64"), mimeType };
+	const reader = Bun.file(file.path).stream().getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > MAX_ATTACHMENT_BYTES)
+				throw new ImagePreparationError("byte-limit");
+			chunks.push(value);
 		}
+	} finally {
+		await reader.cancel();
 	}
+	return prepareImageBytes(Buffer.concat(chunks, size), file.contentType);
+}
+
+/** Prepare bounded raster bytes without reopening a guest-writable filesystem path.
+ * Headers and all GIF/WebP frames must fit 64 MP; encoded bytes must fit 25 MiB. */
+export async function prepareImageBytes(
+	data: Uint8Array,
+	contentType: string,
+): Promise<ModelImage> {
+	if (data.byteLength > MAX_ATTACHMENT_BYTES)
+		throw new ImagePreparationError("byte-limit");
+	const bytes = Buffer.from(data);
+	assertImagePixelBudget(bytes, MAX_SIDE * MAX_SIDE);
+	const mimeType = contentType.split(";")[0]?.trim().toLowerCase() ?? "";
 	const image = await loadImage(bytes);
+	if (
+		bytes.byteLength <= MAX_RAW_BYTES &&
+		Math.max(image.width, image.height) <= MAX_SIDE
+	)
+		return { data: bytes.toString("base64"), mimeType };
 	const scale = DOWNSCALED_SIDE / Math.max(image.width, image.height);
 	const width = Math.max(1, Math.round(image.width * Math.min(1, scale)));
 	const height = Math.max(1, Math.round(image.height * Math.min(1, scale)));

package/src/core/attachments/image-preparation-error.ts

@@ -0,0 +1,14 @@
+/** Image admission failed before native decoding or allocating a bitmap. */
+export class ImagePreparationError extends Error {
+	override readonly name = "ImagePreparationError";
+
+	constructor(readonly reason: "byte-limit" | "pixel-limit" | "invalid-image") {
+		super(
+			{
+				"byte-limit": "Image is larger than 25 MiB.",
+				"pixel-limit": "Image exceeds the 64 MP decoded-pixel budget.",
+				"invalid-image": "Image has an invalid or unsupported raster header.",
+			}[reason],
+		);
+	}
+}

package/src/index.ts

@@ -162,6 +162,7 @@ export {
 	attachReplyFile,
 	REPLY_FILE_LIMITS,
 	ReplyFileError,
+	withReplyFiles,
 } from "./core/reply-files.ts";
 export type {
 	ConversationTurnInput,

package/src/kit/channels.ts

@@ -6,6 +6,8 @@ export {
 	channelSegment,
 	ownerAttachmentDir,
 } from "../core/attachments/attachment-dir.ts";
+export { prepareImageBytes } from "../core/attachments/image-prep.ts";
+export { ImagePreparationError } from "../core/attachments/image-preparation-error.ts";
 export { withAttachmentsBlock } from "../core/attachments/prompt-block.ts";
 export { attachmentsOf } from "../core/attachments/turn-attachments.ts";
 export type { ChannelQueue } from "../core/routing/channel-queue.ts";

package/src/kit/diagnostics.ts

@@ -0,0 +1,43 @@
+/** Tool text that may name a credential: userinfo in URLs, bearer values, and well-known token shapes. */
+const CREDENTIALS: [RegExp, string][] = [
+	[/\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/gi, "$1[redacted]@"],
+	[
+		/\b(authorization|proxy-authorization)\s*[:=]\s*[^\r\n]+/gi,
+		"$1: [redacted]",
+	],
+	[/\b(bearer|basic|token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "$1 [redacted]"],
+	[
+		/\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{16,}|sk-[A-Za-z0-9_-]{16,}|xox[abprs]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,})\b/g,
+		"[redacted]",
+	],
+	[
+		/\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|CREDENTIAL)[A-Z0-9_]*)\s*=\s*\S+/g,
+		"$1=[redacted]",
+	],
+	[
+		/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
+		"[redacted]",
+	],
+];
+
+/**
+ * Text from a failed subprocess or worker, safe to show a model or the owner: credentials are
+ * masked, control characters are removed, and the length is bounded. Empty input returns "".
+ */
+export function scrubDiagnostic(text: string, max = 600): string {
+	let clean = text;
+	for (const [pattern, replacement] of CREDENTIALS)
+		clean = clean.replace(pattern, replacement);
+	clean = Array.from(clean, (char) => {
+		const code = char.charCodeAt(0);
+		// Keep tab and newline; every other control character becomes a space.
+		return code === 9 || code === 10 || code > 31
+			? code === 127
+				? " "
+				: char
+			: " ";
+	})
+		.join("")
+		.trim();
+	return clean.length > max ? `${clean.slice(0, max - 1)}…` : clean;
+}

package/src/kit/index.ts

@@ -6,12 +6,15 @@ export {
 	channelQueue,
 	channelSegment,
 	discordKey,
+	ImagePreparationError,
 	outcome,
 	ownerAttachmentDir,
+	prepareImageBytes,
 	settleTurn,
 	withAttachmentsBlock,
 	withReference,
 } from "./channels.ts";
+export { scrubDiagnostic } from "./diagnostics.ts";
 export type {
 	ChoiceAnswer,
 	ChoiceQuestion,