pi-roundtable-sandbox 0.23.2 → 0.24.1

package/src/commands.ts

@@ -11,7 +11,10 @@ import type { SandboxChannelStore } from "./channel-store.ts";
 /** Owner-only /roundtable sandbox on|off|status; mode changes use the same channel queue as turns. */
 export function sandboxCommands(
 	guard: CommandGuard,
-	channels: SandboxChannelStore,
+	channels: Pick<
+		SandboxChannelStore,
+		"configured" | "disable" | "enable" | "has"
+	>,
 	queue: QueuePort,
 ): InteractionContribution {
 	return {
@@ -47,8 +50,21 @@ export function sandboxCommands(
 						"Sandbox commands require a guild channel.",
 					);
 				const channel = `discord:${interaction.channelId}` as const;
+				const configured = channels.configured(
+					interaction.guildId ?? undefined,
+				);
 				await queue.run(channel, async () => {
 					const action = interaction.options.getSubcommand(true);
+					if (configured) {
+						await interaction.editReply(
+							action === "off"
+								? "This server is sandboxed by configuration (`guilds`); change the configuration to turn it off."
+								: action === "on"
+									? "Sandbox routing is already on: this server is sandboxed by configuration (`guilds`)."
+									: "Sandbox routing is enabled: this server is sandboxed by configuration (`guilds`).",
+						);
+						return;
+					}
 					if (action === "on") channels.enable(channel);
 					else if (action === "off") channels.disable(channel);
 					await interaction.editReply(

package/src/container-driver.ts

@@ -2,7 +2,9 @@ import { realpathSync } from "node:fs";
 import { isAbsolute } from "node:path";
 import {
 	boundedText,
+	CHANNEL_PATH,
 	isRecord,
+	SANDBOX_PROTOCOL_LABEL,
 	type SandboxReply,
 	type SandboxTurn,
 } from "./protocol.ts";
@@ -12,6 +14,8 @@ export interface ContainerSpec {
 	image: string;
 	runDir: string;
 	workspaceDir: string;
+	/** A third, read-write mount at `/channel` holding one channel's own state (`workspace: "server"`). */
+	channelDir?: string;
 	uid: number;
 	gid: number;
 	memoryMb?: number;
@@ -28,6 +32,12 @@ export interface ContainerDriver {
 		turn: SandboxTurn,
 		signal: AbortSignal,
 	): Promise<SandboxReply>;
+	/**
+	 * The worker protocol version the image's `pi-roundtable-sandbox.protocol` label names, or
+	 * undefined for an image without a readable one (an older worker). Asked at startup when an
+	 * option needs a newer worker; a driver that cannot answer stops that startup.
+	 */
+	imageProtocol?(image: string): Promise<number | undefined>;
 }
 
 /** Pure argument generation: no Docker daemon is required to test the isolation boundary. */
@@ -39,6 +49,8 @@ export function containerRunArgs(spec: ContainerSpec): string[] {
 		/\s/.test(spec.image)
 	)
 		throw new Error("invalid container name or image");
+	const mounts = [spec.runDir, spec.workspaceDir];
+	if (spec.channelDir !== undefined) mounts.push(spec.channelDir);
 	if (
 		!Number.isInteger(spec.uid) ||
 		spec.uid <= 0 ||
@@ -46,16 +58,20 @@ export function containerRunArgs(spec: ContainerSpec): string[] {
 		spec.gid <= 0
 	)
 		throw new Error("sandbox requires a non-root user and group");
-	for (const dir of [spec.runDir, spec.workspaceDir]) {
+	for (const dir of mounts) {
 		if (!isAbsolute(dir) || dir === "/" || /[,\n\r]/.test(dir))
 			throw new Error("mount paths must be absolute dedicated directories");
 	}
-	if (
-		spec.runDir === spec.workspaceDir ||
-		spec.runDir.startsWith(`${spec.workspaceDir}/`) ||
-		spec.workspaceDir.startsWith(`${spec.runDir}/`)
-	)
-		throw new Error("broker and workspace mounts must be separate");
+	for (const [index, dir] of mounts.entries())
+		for (const other of mounts.slice(index + 1))
+			if (
+				dir === other ||
+				dir.startsWith(`${other}/`) ||
+				other.startsWith(`${dir}/`)
+			)
+				throw new Error(
+					"broker, workspace and channel mounts must be separate",
+				);
 	const memory = spec.memoryMb ?? 512;
 	const cpus = spec.cpus ?? 1;
 	const pids = spec.pids ?? 64;
@@ -113,6 +129,12 @@ export function containerRunArgs(spec: ContainerSpec): string[] {
 		`type=bind,src=${spec.runDir},dst=/broker,readonly,bind-propagation=rprivate`,
 		"--mount",
 		`type=bind,src=${spec.workspaceDir},dst=/workspace,${spec.workspaceReadOnly ? "readonly," : ""}bind-propagation=rprivate`,
+		...(spec.channelDir === undefined
+			? []
+			: [
+					"--mount",
+					`type=bind,src=${spec.channelDir},dst=${CHANNEL_PATH},bind-propagation=rprivate`,
+				]),
 		"--env",
 		"HOME=/tmp/home",
 		...(command ? ["--entrypoint", command] : []),
@@ -127,6 +149,40 @@ export class DockerContainerDriver implements ContainerDriver {
 		this.#binary = binary;
 	}
 
+	async imageProtocol(image: string): Promise<number | undefined> {
+		if (!image || image.startsWith("-") || /\s/.test(image))
+			throw new Error("invalid container name or image");
+		const child = Bun.spawn(
+			[
+				this.#binary,
+				"image",
+				"inspect",
+				"--format",
+				`{{ index .Config.Labels "${SANDBOX_PROTOCOL_LABEL}" }}`,
+				image,
+			],
+			{ stdout: "pipe", stderr: "pipe" },
+		);
+		const timer = setTimeout(() => child.kill("SIGKILL"), 30_000);
+		try {
+			const [output, , code] = await Promise.all([
+				boundedText(child.stdout, 4096),
+				boundedText(child.stderr, 16 * 1024),
+				child.exited,
+			]);
+			if (code !== 0)
+				throw new Error(
+					`cannot inspect sandbox image ${image}; build it before starting`,
+				);
+			const label = output.trim();
+			return /^\d{1,6}$/.test(label) ? Number(label) : undefined;
+		} finally {
+			clearTimeout(timer);
+			child.kill("SIGKILL");
+			await child.exited;
+		}
+	}
+
 	async run(
 		spec: ContainerSpec,
 		turn: SandboxTurn,
@@ -161,6 +217,9 @@ export class DockerContainerDriver implements ContainerDriver {
 			...spec,
 			runDir: realpathSync(spec.runDir),
 			workspaceDir: realpathSync(spec.workspaceDir),
+			...(spec.channelDir === undefined
+				? {}
+				: { channelDir: realpathSync(spec.channelDir) }),
 		});
 		signal.throwIfAborted();
 		const child = Bun.spawn([this.#binary, ...args], {

package/src/history.ts

@@ -0,0 +1,52 @@
+/**
+ * The conversation history file the sealed worker reads and writes, one per channel: a JSON array
+ * of at most 20 `{ role, content }` entries, oldest first. A host that writes history before a
+ * channel's first turn, such as an import of old chats, uses this encoder so the worker accepts it.
+ */
+export const HISTORY_FILE = "history.json";
+/** The most entries a history file holds; the worker keeps the last 20 after each turn. */
+export const HISTORY_MAX_ENTRIES = 20;
+/** The most bytes one entry's `content` may take, measured as `Buffer.byteLength(JSON.stringify(content))`. */
+export const HISTORY_ENTRY_BYTES = 8192;
+
+export interface SandboxHistoryEntry {
+	role: "user" | "assistant";
+	content: string;
+}
+
+/**
+ * The `content` of a user entry: the JSON text new turns write, naming who spoke and what they
+ * said. The speaker's `id` and `name` are the surface's own, as the worker is told them.
+ */
+export function userHistoryContent(
+	speaker: { id: string; name: string },
+	message: string,
+): string {
+	return JSON.stringify({ speaker, message });
+}
+
+/**
+ * The text of a history file for `entries`, refusing what the worker would: more than 20
+ * entries, a role other than user or assistant, or content over 8,192 bytes. Write it with mode
+ * 0600 into the channel's directory (see `historyFilePath`).
+ */
+export function encodeHistory(entries: readonly SandboxHistoryEntry[]): string {
+	if (entries.length > HISTORY_MAX_ENTRIES)
+		throw new Error(`history holds at most ${HISTORY_MAX_ENTRIES} entries`);
+	for (const entry of entries) {
+		if (
+			typeof entry !== "object" ||
+			entry === null ||
+			(entry.role !== "user" && entry.role !== "assistant") ||
+			typeof entry.content !== "string"
+		)
+			throw new Error("a history entry is { role: user | assistant, content }");
+		if (Buffer.byteLength(JSON.stringify(entry.content)) > HISTORY_ENTRY_BYTES)
+			throw new Error(
+				`a history entry's content is over ${HISTORY_ENTRY_BYTES} bytes`,
+			);
+	}
+	return JSON.stringify(
+		entries.map(({ role, content }) => ({ role, content })),
+	);
+}

package/src/index.ts

@@ -17,6 +17,7 @@ export {
 	type BrokerOptions,
 	type HostTool,
 	type HostToolContext,
+	type HostToolScope,
 	type McpServer,
 	SandboxBroker,
 	type SandboxCredentialScope,
@@ -26,6 +27,7 @@ export { SandboxChannelStore } from "./channel-store.ts";
 export {
 	isSandboxAddress,
 	type SandboxClaimOptions,
+	type SandboxReplyText,
 	sandboxClaim,
 } from "./claim.ts";
 export { sandboxCommands } from "./commands.ts";
@@ -35,6 +37,22 @@ export {
 	containerRunArgs,
 	DockerContainerDriver,
 } from "./container-driver.ts";
+export {
+	encodeHistory,
+	HISTORY_ENTRY_BYTES,
+	HISTORY_FILE,
+	HISTORY_MAX_ENTRIES,
+	type SandboxHistoryEntry,
+	userHistoryContent,
+} from "./history.ts";
+export {
+	channelStateDir,
+	channelWorkspaceDir,
+	guildWorkspaceDir,
+	historyFilePath,
+	workspaceFilesDir,
+} from "./layout.ts";
+export { pageText, textBytes } from "./paging.ts";
 export {
 	collectPiAttachments,
 	type PiAttachmentOptions,
@@ -108,13 +126,30 @@ export {
 	precheckBroker,
 	precheckScriptRunner,
 } from "./precheck-runner.ts";
-export type { SandboxReply, SandboxTurn, ToolSpec } from "./protocol.ts";
+export {
+	BUDGET_DEFAULTS,
+	BUDGET_LIMITS,
+	FILES_DEFAULTS,
+	SANDBOX_PROTOCOL,
+	SANDBOX_PROTOCOL_LABEL,
+	type SandboxBudgets,
+	type SandboxFiles,
+	type SandboxReply,
+	type SandboxTurn,
+	type ToolSpec,
+	toolResultTextBytes,
+} from "./protocol.ts";
 export {
 	type ResearchTools,
 	type SandboxResearchOptions,
 	SandboxResearchWorker,
 } from "./research-worker.ts";
-export { SandboxRuntime, type SandboxRuntimeOptions } from "./runtime.ts";
+export {
+	SandboxRuntime,
+	type SandboxRuntimeOptions,
+	type SandboxTurnContext,
+	SandboxTurnRefused,
+} from "./runtime.ts";
 export {
 	assertPublicUrl,
 	isPublicAddress,

package/src/layout.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import type { ChannelKey } from "pi-roundtable";
+import { HISTORY_FILE } from "./history.ts";
+import { FILES_DIR } from "./protocol.ts";
+
+const digest = (text: string): string =>
+	createHash("sha256").update(text).digest("hex");
+
+/** Directory name of a channel's own workspace (`workspace: "channel"`, and a message with no guild). */
+export function channelWorkspaceName(channel: ChannelKey): string {
+	return digest(channel);
+}
+/** Directory name of a guild's shared workspace (`workspace: "server"`). */
+export function guildWorkspaceName(surface: string, guild: string): string {
+	return `guild-${digest(`guild\0${surface}:${guild}`)}`;
+}
+/** Directory name of a channel's own state directory, mounted at `/channel` in `"server"` mode. */
+export function channelStateName(channel: ChannelKey): string {
+	return `state-${digest(`state\0${channel}`)}`;
+}
+
+/** A channel's own workspace under `workspaceRoot`; memory, files and history live in it. */
+export function channelWorkspaceDir(
+	workspaceRoot: string,
+	channel: ChannelKey,
+): string {
+	return join(workspaceRoot, channelWorkspaceName(channel));
+}
+/**
+ * The workspace every sandbox channel of one guild shares in `workspace: "server"` mode, for the
+ * guild `guild` of `surface` (`"discord"`). It holds memory notes and workspace files.
+ */
+export function guildWorkspaceDir(
+	workspaceRoot: string,
+	surface: string,
+	guild: string,
+): string {
+	return join(workspaceRoot, guildWorkspaceName(surface, guild));
+}
+/**
+ * One channel's state directory in `workspace: "server"` mode; its conversation history
+ * (`historyFilePath`) lives there, and a turn sees only its own channel's.
+ */
+export function channelStateDir(
+	workspaceRoot: string,
+	channel: ChannelKey,
+): string {
+	return join(workspaceRoot, channelStateName(channel));
+}
+/** The history file inside a channel's state directory (or its workspace in `"channel"` mode). */
+export function historyFilePath(directory: string): string {
+	return join(directory, HISTORY_FILE);
+}
+/** Where the file tools keep a workspace's files; an import writes its files here. */
+export function workspaceFilesDir(workspaceDir: string): string {
+	return join(workspaceDir, FILES_DIR);
+}

package/src/paging.ts

@@ -0,0 +1,57 @@
+/** `Buffer.byteLength(JSON.stringify(text))`: how the sealed worker measures text against a budget. */
+export function textBytes(text: string): number {
+	return Buffer.byteLength(JSON.stringify(text));
+}
+
+const isHigh = (code: number): boolean => code >= 0xd800 && code <= 0xdbff;
+const isLow = (code: number): boolean => code >= 0xdc00 && code <= 0xdfff;
+
+/**
+ * One page of `text` from character `offset` (a JavaScript string index), as much as fits
+ * `budget` under `measure` (the worker's `textBytes` by default; a host tool whose result the
+ * broker wraps passes `toolResultTextBytes` and its `resultBytes`). When more text follows, the
+ * page begins with the line `[More: next offset N]` so a cut never removes it; pass N as the
+ * next call's offset. Throws on an offset that is not a whole position in the text.
+ */
+export function pageText(
+	text: string,
+	offset: number,
+	budget: number,
+	measure: (text: string) => number = textBytes,
+): string {
+	if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length)
+		throw new RangeError(
+			`offset must be a whole number from 0 to ${text.length}`,
+		);
+	if (
+		offset > 0 &&
+		offset < text.length &&
+		isHigh(text.charCodeAt(offset - 1)) &&
+		isLow(text.charCodeAt(offset))
+	)
+		throw new RangeError("offset falls inside a character");
+	if (offset === text.length)
+		return `(No text at offset ${offset}: that is the end of the text.)`;
+	const rest = text.slice(offset);
+	if (measure(rest) <= budget) return rest;
+	const header = (end: number): string => `[More: next offset ${end}]\n`;
+	const fits = (end: number): boolean =>
+		measure(header(end) + text.slice(offset, end)) <= budget;
+	let low = offset;
+	let high = text.length - 1;
+	while (low < high) {
+		const middle = Math.ceil((low + high) / 2);
+		if (fits(middle)) low = middle;
+		else high = middle - 1;
+	}
+	// Never end between the halves of a surrogate pair.
+	if (
+		low > offset &&
+		isHigh(text.charCodeAt(low - 1)) &&
+		isLow(text.charCodeAt(low))
+	)
+		low--;
+	if (low === offset)
+		throw new Error("the result budget is too small for one character");
+	return header(low) + text.slice(offset, low);
+}

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";
 
@@ -13,10 +13,22 @@ export interface SandboxOptions
 	stateFile: string;
 	/** Used only when stateFile does not yet exist. */
 	initialChannels?: readonly ChannelKey[];
+	/**
+	 * Discord guild ids whose every channel and thread is a sandbox channel, with no
+	 * `/roundtable sandbox on`; ids are validated at startup. A configured guild cannot be turned
+	 * off by command. Direct messages and other guilds are not affected.
+	 */
+	guilds?: readonly string[];
 	/** Host login provider used for each model call, unless apiKey is supplied. */
 	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;
@@ -28,7 +40,7 @@ export function sandbox(options: SandboxOptions) {
 	return definePlugin({
 		name: "sandbox",
 		provides: [SANDBOX],
-		setup: (context) => {
+		setup: async (context) => {
 			const runtime = new SandboxRuntime({
 				...options,
 				apiKey:
@@ -53,7 +65,10 @@ export function sandbox(options: SandboxOptions) {
 			const channels = new SandboxChannelStore(
 				stateFile,
 				options.initialChannels,
+				{ guilds: options.guilds },
 			);
+			// Last of the cheap checks: a typo above fails fast, without a `docker inspect`.
+			await runtime.verifyImage();
 			context.services.provide(SANDBOX, { channels, runtime });
 			const discord = context.services.find(DISCORD);
 			if (discord)
@@ -66,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",
 							),
 					}),
 				],

package/src/protocol.ts

@@ -1,6 +1,15 @@
 export const DUMMY_KEY = "sandbox-dummy-key";
 export const BROKER_PATH = "/broker/broker.sock";
 export const WORKSPACE_PATH = "/workspace";
+/** Where a channel's own state directory is mounted in `workspace: "server"` mode. */
+export const CHANNEL_PATH = "/channel";
+/** The image label naming the worker protocol version an image speaks. */
+export const SANDBOX_PROTOCOL_LABEL = "pi-roundtable-sandbox.protocol";
+/**
+ * The worker protocol this package speaks: 2 adds `historyDir`, `budgets` and the file and skill
+ * tools. An image labelled lower, or unlabelled, is an older worker.
+ */
+export const SANDBOX_PROTOCOL = 2;
 
 export interface ToolSpec {
 	name: string;
@@ -8,6 +17,125 @@ export interface ToolSpec {
 	parameters: Record<string, unknown>;
 }
 
+/**
+ * Byte budgets the sealed worker enforces, each measured as
+ * `Buffer.byteLength(JSON.stringify(text))`. An absent key means the worker's default.
+ */
+export interface SandboxBudgets {
+	/** The system prompt, including a skill index. */
+	promptBytes?: number;
+	/** One tool result, as the worker measures it after encoding. */
+	toolResultBytes?: number;
+	/** One model request; the oldest history and tool-call groups are dropped to fit. */
+	requestBytes?: number;
+}
+export const BUDGET_DEFAULTS = {
+	promptBytes: 8192,
+	toolResultBytes: 4096,
+	requestBytes: 196_608,
+} as const satisfies Required<SandboxBudgets>;
+export const BUDGET_LIMITS = {
+	promptBytes: { min: 256, max: 32_768 },
+	toolResultBytes: { min: 256, max: 32_768 },
+	requestBytes: { min: 4096, max: 196_608 },
+} as const;
+
+/** The most the worker keeps of the current message (JSON-encoded bytes). */
+export const CURRENT_MESSAGE_MAX_BYTES = 48 * 1024;
+/** The speaker memory and the channel notes in the system line, 4 KiB each. */
+export const MEMORY_ROOM_BYTES = 8192;
+/** The most tool calls one model reply may make. */
+export const MAX_TOOL_CALLS = 8;
+/** The least room per tool result a request must leave when a reply makes the most calls. */
+export const MIN_TOOL_RESULT_ROOM_BYTES = 1024;
+
+/**
+ * Why `requestBytes` cannot hold one turn's fixed parts plus a minimum of room for every
+ * result of a full reply of tool calls, or undefined when it can. Sizes are the worker's measure.
+ */
+export function requestBytesError(
+	budgets: SandboxBudgets | undefined,
+): string | undefined {
+	const promptBytes = budgets?.promptBytes ?? BUDGET_DEFAULTS.promptBytes;
+	const requestBytes = budgets?.requestBytes ?? BUDGET_DEFAULTS.requestBytes;
+	const toolRoom = MAX_TOOL_CALLS * MIN_TOOL_RESULT_ROOM_BYTES;
+	const needed =
+		promptBytes + MEMORY_ROOM_BYTES + CURRENT_MESSAGE_MAX_BYTES + toolRoom;
+	if (requestBytes >= needed) return undefined;
+	return `budgets.requestBytes ${requestBytes} cannot hold budgets.promptBytes ${promptBytes} + ${MEMORY_ROOM_BYTES} bytes of memory notes + ${CURRENT_MESSAGE_MAX_BYTES} bytes for the current message + ${toolRoom} bytes for ${MAX_TOOL_CALLS} tool results of ${MIN_TOOL_RESULT_ROOM_BYTES} bytes (${needed} in all); raise requestBytes or lower promptBytes`;
+}
+
+/** Why `value` is not a valid budgets object, or undefined when it is one. */
+export function budgetsError(value: unknown): string | undefined {
+	if (!isRecord(value)) return "budgets must be an object";
+	for (const name of Object.keys(value)) {
+		if (!(name in BUDGET_LIMITS)) return `unknown budget ${name}`;
+	}
+	for (const name of Object.keys(BUDGET_LIMITS) as (keyof SandboxBudgets)[]) {
+		const entry = value[name];
+		if (entry === undefined) continue;
+		const { min, max } = BUDGET_LIMITS[name];
+		if (
+			!Number.isSafeInteger(entry) ||
+			(entry as number) < min ||
+			(entry as number) > max
+		)
+			return `budgets.${name} must be an integer from ${min} to ${max}`;
+	}
+	return undefined;
+}
+
+/**
+ * What the broker's `{"text":…}` wrapper costs a host tool's result in the worker's measure:
+ * the wrapper is encoded twice, once into the broker's reply and once into the tool message.
+ */
+export const TOOL_RESULT_WRAPPER_BYTES = 17;
+
+/**
+ * The size of a host tool's result `text` in the worker's measure after the wrapper, to compare
+ * with `HostToolContext.resultBytes`: the bytes of its text encoded twice, so a newline or a
+ * quote costs four.
+ */
+export function toolResultTextBytes(text: string): number {
+	return Buffer.byteLength(JSON.stringify(JSON.stringify(text))) - 2;
+}
+
+/** The workspace file tools' limits, as the turn carries them. */
+export interface SandboxFiles {
+	/** The most UTF-8 bytes one file may hold. */
+	maxFileBytes: number;
+	/** The most bytes everything under `files/` may hold. */
+	maxTotalBytes: number;
+}
+export const FILES_DIR = "files";
+export const FILES_DEFAULTS = {
+	maxFileBytes: 256 * 1024,
+	maxTotalBytes: 32 * 1024 * 1024,
+} as const satisfies SandboxFiles;
+const FILES_FILE_CEILING = 16 * 1024 * 1024;
+const FILES_TOTAL_CEILING = 100 * 1024 ** 3;
+
+/** Why `value` is not a valid files limit pair, or undefined when it is one. */
+export function filesError(value: unknown): string | undefined {
+	if (!isRecord(value)) return "files must be an object of limits";
+	const { maxFileBytes, maxTotalBytes } = value;
+	if (
+		!Number.isSafeInteger(maxFileBytes) ||
+		(maxFileBytes as number) < 1 ||
+		(maxFileBytes as number) > FILES_FILE_CEILING
+	)
+		return `files.maxFileBytes must be an integer from 1 to ${FILES_FILE_CEILING}`;
+	if (
+		!Number.isSafeInteger(maxTotalBytes) ||
+		(maxTotalBytes as number) < 1 ||
+		(maxTotalBytes as number) > FILES_TOTAL_CEILING
+	)
+		return `files.maxTotalBytes must be an integer from 1 to ${FILES_TOTAL_CEILING}`;
+	if ((maxFileBytes as number) > (maxTotalBytes as number))
+		return "files.maxFileBytes must not exceed files.maxTotalBytes";
+	return undefined;
+}
+
 export interface SandboxTurn {
 	text: string;
 	speaker: { id: string; name: string };
@@ -16,6 +144,12 @@ export interface SandboxTurn {
 	timeZone: string;
 	tools: ToolSpec[];
 	reset?: boolean;
+	/** Absent unless the operator set a budget; the worker then keeps its defaults. */
+	budgets?: SandboxBudgets;
+	/** Present when the file tools are on; absent means the worker offers none. */
+	files?: SandboxFiles;
+	/** Where the history file lives; absent means in the workspace, as before. */
+	historyDir?: typeof CHANNEL_PATH;
 	mcp: { server: string; tools: ToolSpec[] }[];
 }
 
@@ -49,6 +183,10 @@ export function isSandboxTurn(value: unknown): value is SandboxTurn {
 		typeof value.prompt === "string" &&
 		typeof value.timeZone === "string" &&
 		(value.reset === undefined || typeof value.reset === "boolean") &&
+		(value.budgets === undefined ||
+			budgetsError(value.budgets) === undefined) &&
+		(value.historyDir === undefined || value.historyDir === CHANNEL_PATH) &&
+		(value.files === undefined || filesError(value.files) === undefined) &&
 		Array.isArray(value.tools) &&
 		value.tools.every(isToolSpec) &&
 		Array.isArray(value.mcp) &&