pi-roundtable-sandbox 0.7.0

package/src/container-driver.ts

@@ -0,0 +1,193 @@
+import { realpathSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import {
+	boundedText,
+	isRecord,
+	type SandboxReply,
+	type SandboxTurn,
+} from "./protocol.ts";
+
+export interface ContainerSpec {
+	name: string;
+	image: string;
+	runDir: string;
+	workspaceDir: string;
+	uid: number;
+	gid: number;
+	memoryMb?: number;
+	cpus?: number;
+	pids?: number;
+}
+export interface ContainerDriver {
+	run(
+		spec: ContainerSpec,
+		turn: SandboxTurn,
+		signal: AbortSignal,
+	): Promise<SandboxReply>;
+}
+
+/** Pure argument generation: no Docker daemon is required to test the isolation boundary. */
+export function containerRunArgs(spec: ContainerSpec): string[] {
+	if (
+		!/^[a-z0-9][a-z0-9_.-]{0,90}$/.test(spec.name) ||
+		!spec.image ||
+		spec.image.startsWith("-") ||
+		/\s/.test(spec.image)
+	)
+		throw new Error("invalid container name or image");
+	if (
+		!Number.isInteger(spec.uid) ||
+		spec.uid <= 0 ||
+		!Number.isInteger(spec.gid) ||
+		spec.gid <= 0
+	)
+		throw new Error("sandbox requires a non-root user and group");
+	for (const dir of [spec.runDir, spec.workspaceDir]) {
+		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");
+	const memory = spec.memoryMb ?? 512;
+	const cpus = spec.cpus ?? 1;
+	const pids = spec.pids ?? 64;
+	if (
+		!Number.isSafeInteger(memory) ||
+		memory < 64 ||
+		!Number.isFinite(cpus) ||
+		cpus <= 0 ||
+		!Number.isSafeInteger(pids) ||
+		pids < 8
+	)
+		throw new Error("invalid resource limits");
+	return [
+		"run",
+		"--rm",
+		"--interactive",
+		"--sig-proxy=false",
+		"--log-driver",
+		"none",
+		"--pull",
+		"never",
+		"--name",
+		spec.name,
+		"--network",
+		"none",
+		"--read-only",
+		"--cap-drop",
+		"ALL",
+		"--security-opt",
+		"no-new-privileges:true",
+		"--user",
+		`${spec.uid}:${spec.gid}`,
+		"--memory",
+		`${memory}m`,
+		"--memory-swap",
+		`${memory}m`,
+		"--cpus",
+		String(cpus),
+		"--pids-limit",
+		String(pids),
+		"--ulimit",
+		"nofile=256:256",
+		"--tmpfs",
+		"/tmp:rw,noexec,nosuid,nodev,size=64m,mode=1777",
+		"--mount",
+		`type=bind,src=${spec.runDir},dst=/broker,readonly,bind-propagation=rprivate`,
+		"--mount",
+		`type=bind,src=${spec.workspaceDir},dst=/workspace,bind-propagation=rprivate`,
+		"--env",
+		"HOME=/tmp/home",
+		spec.image,
+	];
+}
+
+export class DockerContainerDriver implements ContainerDriver {
+	readonly #binary: string;
+	constructor(binary = "docker") {
+		this.#binary = binary;
+	}
+
+	async run(
+		spec: ContainerSpec,
+		turn: SandboxTurn,
+		signal: AbortSignal,
+	): Promise<SandboxReply> {
+		// Canonical paths prevent symlinks in operator configuration selecting a different mount.
+		const args = containerRunArgs({
+			...spec,
+			runDir: realpathSync(spec.runDir),
+			workspaceDir: realpathSync(spec.workspaceDir),
+		});
+		signal.throwIfAborted();
+		const child = Bun.spawn([this.#binary, ...args], {
+			stdin: "pipe",
+			stdout: "pipe",
+			stderr: "pipe",
+		});
+		// SIGTERM can be proxied into an uncooperative PID 1 forever; kill this CLI directly.
+		const abort = () => child.kill("SIGKILL");
+		signal.addEventListener("abort", abort, { once: true });
+		try {
+			child.stdin.write(JSON.stringify(turn));
+			child.stdin.end();
+			const [output, , code] = await Promise.all([
+				boundedText(child.stdout, 2 * 1024 * 1024),
+				boundedText(child.stderr, 128 * 1024),
+				child.exited,
+			]);
+			signal.throwIfAborted();
+			if (code !== 0) throw new Error("sandbox worker failed");
+			const reply: unknown = JSON.parse(output);
+			if (
+				!isRecord(reply) ||
+				typeof reply.ok !== "boolean" ||
+				typeof reply.text !== "string" ||
+				reply.text.length > 100_000
+			)
+				throw new Error("invalid sandbox reply");
+			return { ok: reply.ok, text: reply.text };
+		} finally {
+			signal.removeEventListener("abort", abort);
+			child.kill("SIGKILL");
+			await child.exited;
+			// Do not wait on a cooperative container exit; force-remove its exact name.
+			await this.#remove(spec.name);
+			if (signal.aborted || child.exitCode !== 0) {
+				// Cover the short create/attach race after killing the run client.
+				await Bun.sleep(100);
+				await this.#remove(spec.name);
+			}
+		}
+	}
+
+	async #remove(name: string): Promise<void> {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const cleanup = Bun.spawn([this.#binary, "rm", "--force", name], {
+				stdout: "ignore",
+				stderr: "pipe",
+			});
+			const timer = setTimeout(() => cleanup.kill("SIGKILL"), 5000);
+			try {
+				const [error, code] = await Promise.all([
+					boundedText(cleanup.stderr, 16 * 1024),
+					cleanup.exited,
+				]);
+				if (code === 0 || /No such (container|object)/i.test(error)) return;
+				if (attempt === 2 || !/removal.*already in progress/is.test(error))
+					throw new Error(
+						"sandbox container cleanup failed; inspect this installation's containers",
+					);
+			} finally {
+				clearTimeout(timer);
+				cleanup.kill("SIGKILL");
+				await cleanup.exited;
+			}
+			await Bun.sleep(100 * (attempt + 1));
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+export {
+	type BrokerListener,
+	type BrokerOptions,
+	type HostTool,
+	type HostToolContext,
+	type McpServer,
+	SandboxBroker,
+} from "./broker.ts";
+export { SandboxChannelStore } from "./channel-store.ts";
+export {
+	isSandboxAddress,
+	type SandboxClaimOptions,
+	sandboxClaim,
+} from "./claim.ts";
+export { sandboxCommands } from "./commands.ts";
+export {
+	type ContainerDriver,
+	type ContainerSpec,
+	containerRunArgs,
+	DockerContainerDriver,
+} from "./container-driver.ts";
+export {
+	SANDBOX,
+	type SandboxOptions,
+	type SandboxService,
+	sandbox,
+} from "./plugin.ts";
+export type { SandboxReply, SandboxTurn, ToolSpec } from "./protocol.ts";
+export { SandboxRuntime, type SandboxRuntimeOptions } from "./runtime.ts";

package/src/model-input.ts

@@ -0,0 +1,177 @@
+import {
+	validFunctionName as functionName,
+	validCallId as identifier,
+	isRecord,
+} from "./protocol.ts";
+
+interface ModelInput {
+	messages: Record<string, unknown>[];
+	tools?: Record<string, unknown>[];
+}
+
+function localSchema(value: unknown): boolean {
+	if (typeof value === "boolean") return true;
+	if (!isRecord(value)) return false;
+	for (const key of [
+		"$ref",
+		"$dynamicRef",
+		"$recursiveRef",
+		"$schema",
+		"$id",
+	]) {
+		if (
+			value[key] !== undefined &&
+			(typeof value[key] !== "string" || !value[key].startsWith("#"))
+		)
+			return false;
+	}
+	if (
+		value.$vocabulary !== undefined &&
+		(!isRecord(value.$vocabulary) ||
+			Object.keys(value.$vocabulary).some((uri) => !uri.startsWith("#")))
+	)
+		return false;
+	// Recurse only into schema positions; property names and enum/const data are not keywords.
+	for (const key of [
+		"properties",
+		"patternProperties",
+		"$defs",
+		"definitions",
+		"dependentSchemas",
+	]) {
+		if (
+			value[key] !== undefined &&
+			(!isRecord(value[key]) || !Object.values(value[key]).every(localSchema))
+		)
+			return false;
+	}
+	for (const key of [
+		"items",
+		"contains",
+		"additionalProperties",
+		"unevaluatedProperties",
+		"unevaluatedItems",
+		"propertyNames",
+		"not",
+		"if",
+		"then",
+		"else",
+		"contentSchema",
+		"additionalItems",
+	]) {
+		if (
+			value[key] !== undefined &&
+			!(Array.isArray(value[key])
+				? value[key].every(localSchema)
+				: localSchema(value[key]))
+		)
+			return false;
+	}
+	for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+		if (
+			value[key] !== undefined &&
+			(!Array.isArray(value[key]) || !value[key].every(localSchema))
+		)
+			return false;
+	}
+	if (
+		isRecord(value.dependencies) &&
+		Object.values(value.dependencies).some(
+			(entry) => !Array.isArray(entry) && !localSchema(entry),
+		)
+	)
+		return false;
+	return true;
+}
+
+/** Model traffic is text plus function calls only: no account files, media URLs or native provider tools. */
+export function modelInput(
+	body: Record<string, unknown>,
+): ModelInput | undefined {
+	if (!Array.isArray(body.messages) || body.messages.length > 128)
+		return undefined;
+	const messages: Record<string, unknown>[] = [];
+	for (const raw of body.messages) {
+		if (
+			!isRecord(raw) ||
+			typeof raw.role !== "string" ||
+			!["system", "user", "assistant", "tool"].includes(raw.role) ||
+			typeof raw.content !== "string"
+		)
+			return undefined;
+		if (
+			Object.keys(raw).some(
+				(key) =>
+					!["role", "content", "tool_calls", "tool_call_id"].includes(key),
+			)
+		)
+			return undefined;
+		const message: Record<string, unknown> = {
+			role: raw.role,
+			content: raw.content,
+		};
+		if (raw.tool_calls !== undefined) {
+			if (
+				raw.role !== "assistant" ||
+				!Array.isArray(raw.tool_calls) ||
+				raw.tool_calls.length > 8
+			)
+				return undefined;
+			const calls: Record<string, unknown>[] = [];
+			for (const call of raw.tool_calls) {
+				if (
+					!isRecord(call) ||
+					call.type !== "function" ||
+					!identifier(call.id) ||
+					!isRecord(call.function) ||
+					!functionName(call.function.name) ||
+					typeof call.function.arguments !== "string"
+				)
+					return undefined;
+				calls.push({
+					id: call.id,
+					type: "function",
+					function: {
+						name: call.function.name,
+						arguments: call.function.arguments,
+					},
+				});
+			}
+			message.tool_calls = calls;
+		}
+		if (raw.role === "tool") {
+			if (!identifier(raw.tool_call_id)) return undefined;
+			message.tool_call_id = raw.tool_call_id;
+		} else if (raw.tool_call_id !== undefined) return undefined;
+		messages.push(message);
+	}
+	let tools: Record<string, unknown>[] | undefined;
+	if (body.tools !== undefined) {
+		if (!Array.isArray(body.tools) || body.tools.length > 128) return undefined;
+		tools = [];
+		const names = new Set<string>();
+		for (const tool of body.tools) {
+			if (
+				!isRecord(tool) ||
+				tool.type !== "function" ||
+				!isRecord(tool.function) ||
+				!functionName(tool.function.name) ||
+				names.has(tool.function.name) ||
+				typeof tool.function.description !== "string" ||
+				!isRecord(tool.function.parameters) ||
+				!localSchema(tool.function.parameters)
+			)
+				return undefined;
+			names.add(tool.function.name);
+			tools.push({
+				type: "function",
+				function: {
+					name: tool.function.name,
+					description: tool.function.description,
+					parameters: tool.function.parameters,
+				},
+			});
+		}
+	}
+	return { messages, ...(tools ? { tools } : {}) };
+}

package/src/plugin.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, realpathSync } from "node:fs";
+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 { sandboxCommands } from "./commands.ts";
+import { SandboxRuntime, type SandboxRuntimeOptions } from "./runtime.ts";
+
+export interface SandboxOptions
+	extends Omit<SandboxRuntimeOptions, "apiKey" | "timeZone"> {
+	/** Persistent, host-only file outside both mounted directories. */
+	stateFile: string;
+	/** Used only when stateFile does not yet exist. */
+	initialChannels?: readonly ChannelKey[];
+	/** Host login provider used for each model call, unless apiKey is supplied. */
+	provider?: string;
+	apiKey?: SandboxRuntimeOptions["apiKey"];
+}
+export interface SandboxService {
+	channels: SandboxChannelStore;
+	runtime: SandboxRuntime;
+}
+export const SANDBOX = serviceKey<SandboxService>("sandbox.channels");
+
+export function sandbox(options: SandboxOptions) {
+	return definePlugin({
+		name: "sandbox",
+		provides: [SANDBOX],
+		setup: (context) => {
+			const runtime = new SandboxRuntime({
+				...options,
+				apiKey:
+					options.apiKey ??
+					(() => context.apiKey(options.provider ?? "openai")),
+				timeZone: context.env.timeZone,
+			});
+			if (!isAbsolute(options.stateFile))
+				throw new Error("stateFile must be absolute");
+			mkdirSync(dirname(options.stateFile), { recursive: true, mode: 0o700 });
+			const stateFile = resolve(
+				realpathSync(dirname(options.stateFile)),
+				options.stateFile.split("/").at(-1) ?? "",
+			);
+			for (const root of [
+				realpathSync(options.runRoot),
+				realpathSync(options.workspaceRoot),
+			]) {
+				if (stateFile === root || stateFile.startsWith(`${root}/`))
+					throw new Error("routing state must stay outside sandbox mounts");
+			}
+			const channels = new SandboxChannelStore(
+				stateFile,
+				options.initialChannels,
+			);
+			context.services.provide(SANDBOX, { channels, runtime });
+			const discord = context.services.find(DISCORD);
+			if (discord)
+				discord.commands.add(
+					sandboxCommands(discord.guard, channels, context.queue),
+				);
+			return {
+				channels: [
+					sandboxClaim({
+						channels,
+						runtime,
+						surfaces: context.surfaces,
+						reportFailure: (channel) =>
+							context.logger.error(
+								{ channel },
+								"sandbox turn failed; inspect container cleanup and broker configuration",
+							),
+					}),
+				],
+				services: [
+					{
+						name: "sandbox-runtime",
+						busy: () => runtime.busy(),
+						stop: () => runtime.dispose(),
+					},
+				],
+			};
+		},
+	});
+}

package/src/protocol.ts

@@ -0,0 +1,108 @@
+export const DUMMY_KEY = "sandbox-dummy-key";
+export const BROKER_PATH = "/broker/broker.sock";
+export const WORKSPACE_PATH = "/workspace";
+
+export interface ToolSpec {
+	name: string;
+	description: string;
+	parameters: Record<string, unknown>;
+}
+
+export interface SandboxTurn {
+	text: string;
+	speaker: { id: string; name: string };
+	model: string;
+	prompt: string;
+	timeZone: string;
+	tools: ToolSpec[];
+	reset?: boolean;
+	mcp: { server: string; tools: ToolSpec[] }[];
+}
+
+export interface SandboxReply {
+	ok: boolean;
+	text: string;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function isToolSpec(value: unknown): value is ToolSpec {
+	return (
+		isRecord(value) &&
+		typeof value.name === "string" &&
+		validName(value.name) &&
+		typeof value.description === "string" &&
+		isRecord(value.parameters)
+	);
+}
+
+export function isSandboxTurn(value: unknown): value is SandboxTurn {
+	return (
+		isRecord(value) &&
+		typeof value.text === "string" &&
+		isRecord(value.speaker) &&
+		typeof value.speaker.id === "string" &&
+		typeof value.speaker.name === "string" &&
+		typeof value.model === "string" &&
+		typeof value.prompt === "string" &&
+		typeof value.timeZone === "string" &&
+		(value.reset === undefined || typeof value.reset === "boolean") &&
+		Array.isArray(value.tools) &&
+		value.tools.every(isToolSpec) &&
+		Array.isArray(value.mcp) &&
+		value.mcp.every(
+			(server) =>
+				isRecord(server) &&
+				typeof server.server === "string" &&
+				validName(server.server) &&
+				Array.isArray(server.tools) &&
+				server.tools.every(isToolSpec),
+		)
+	);
+}
+
+export function validName(value: string): boolean {
+	return /^[a-z][a-z0-9_]{0,47}$/.test(value);
+}
+
+export function validFunctionName(name: unknown): name is string {
+	return typeof name === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(name);
+}
+
+export function validCallId(id: unknown): id is string {
+	return typeof id === "string" && id.length > 0 && id.length <= 128;
+}
+
+/** Bound untrusted input before JSON parsing, including chunked bodies. */
+export async function boundedText(
+	stream: ReadableStream<Uint8Array> | null,
+	limit: number,
+): Promise<string> {
+	if (!stream) return "";
+	const reader = stream.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > limit) {
+				await reader.cancel();
+				throw new Error("body too large");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	const data = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		data.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(data);
+}