pi-roundtable 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -5,6 +5,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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,9 @@ 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 |
 | `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.3",
 	"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/index.ts

@@ -6,8 +6,10 @@ export {
 	channelQueue,
 	channelSegment,
 	discordKey,
+	ImagePreparationError,
 	outcome,
 	ownerAttachmentDir,
+	prepareImageBytes,
 	settleTurn,
 	withAttachmentsBlock,
 	withReference,