pi-roundtable-sandbox 0.7.10 → 0.7.11

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.7.11
+
+- `precheckScriptRunner` runs agents' precheck scripts (pi-roundtable 0.7.11) in a sealed container per run: no network, a read-only root, no capabilities, a non-root user, an empty workspace, and a per-run broker (`precheckBroker`) that forwards only single `tools/call` requests of the tools `grant(scope)` allows, with the host's credential (`PrecheckMcpServer`). The container runs `worker/precheck-main.ts` (`PRECHECK_ENTRYPOINT`, `PrecheckWorkerInput`), which gives the script `mcp.call`, `mcp.json`, `firedAt`, `timeZone`, `today`, and `schedule`.
+- A script's workspace is mounted read-only (`ContainerSpec.workspaceReadOnly`), so it writes only to the container's bounded `/tmp`. The broker refuses an answer that carries the credential plainly, escaped, inside JSON text, base64-encoded, or as a key; joins an SSE event's `data:` lines; and refuses a second call while one is pending (409) without spending the budget. The script's console output goes to stderr and never into its answer, and `grant` receives the creator's `tier`.
+- `ContainerSpec` takes `entrypoint`, and `DockerContainerDriver.exec` runs a sealed container with any input and a bounded output (`PrecheckContainerDriver`); `worker/Dockerfile` includes the precheck worker.
+
 ## 0.7.10
 
 - Compact Pi worker sessions with the core's tiers (300,000 tokens through a host compactor, Pi's summary past 500,000), through the new `compaction` option (`PiCompactor`: `engine`, `compact(request, { channel, signal })`, `timeoutMs`, `maxRequestBytes`) and the protocol types `PiCompactRequest`, `PiCompaction`, `PiCompactResponse`, `PiCompactionReport`, `PiCompactMessage` and `PiWorkerConfig`; the host logs every compaction and fallback per channel.

package/README.md

@@ -364,6 +364,53 @@ One of `search` with a fetch option, or `tools`, is required.
 Host search/model credentials stay in the trusted host process, and report delivery must remain in the declared guest channel.
 These hooks broaden the sealed threat model: review every adapter, apply provider spend limits and host quotas, and never substitute an unrestricted default delegation worker.
 
+## Precheck scripts
+
+`precheckScriptRunner` lets agents write a schedule's precheck themselves (pi-roundtable 0.7.11 or later): a short JavaScript module that decides, before the scheduled turn, whether the agent is woken at all.
+The core stores and parses the script but never runs it; this runner runs it in a sealed container, one per run.
+Register it from a trusted plugin of your own:
+
+```ts
+import { PRECHECKS, definePlugin } from "pi-roundtable";
+import { precheckScriptRunner } from "pi-roundtable-sandbox";
+
+export const precheckScripts = definePlugin({
+  name: "precheck-scripts",
+  setup: ({ services }) => {
+    services.get(PRECHECKS).useScriptRunner(precheckScriptRunner({
+      image: "pi-roundtable-sandbox:pi",
+      runRoot: "/tmp/roundtable-precheck",
+      // The host's non-root user, who owns runRoot; root is refused.
+      uid: 1000,
+      gid: 1000,
+      // Never more than the schedule's agent may call itself; [] leaves the script no way out.
+      grant: ({ channel, target }) => grantsFor(channel, target),
+    }));
+    return {};
+  },
+});
+```
+
+`grant({ channel, target })` returns the `PrecheckMcpServer`s a script for that schedule may call: `{ name, url, tools, token? }`.
+The script calls a server by `name`, only the listed `tools`, and only with single `tools/call` requests; every other server, tool, method, query, and extra credential is refused, and refused calls count against the run's budget (`maxCalls`, default 16).
+`url` is a fixed HTTPS Streamable HTTP endpoint answering with JSON or one SSE event; `token` is read on the host for each call and inserted by the broker. An answer that carries it, plainly, inside JSON text, or base64-encoded, is refused; this catches an echo, not an upstream set on leaking it, so grant only upstreams you trust.
+Calls run one at a time; a second call while one is pending is refused.
+Neither the endpoint nor the credential reaches the container.
+
+Each run gets:
+
+- The same sealed `docker run` as a guest turn: `--network none`, a read-only root, all capabilities dropped, `no-new-privileges`, the host's non-root user, 256 MiB, one CPU, and 32 processes by default (`limits`).
+- A fresh broker socket and an empty workspace under `runRoot`, both removed afterwards; the workspace is mounted read-only, so a script writes only to the container's 64 MiB `/tmp`.
+- When the host stops, the scheduler aborts running scripts and waits for their containers to be removed.
+- The worker `worker/precheck-main.ts` as its entrypoint (`PRECHECK_ENTRYPOINT`, the Pi image's layout; pass `entrypoint` for another image, such as `["bun", "/app/worker/precheck-main.ts"]` for `worker/Dockerfile`'s).
+- At most `timeoutMs` (default 60 seconds); on timeout the container is killed and the turn wakes with the error.
+
+The script is `export default async ({ mcp, firedAt, timeZone, today, schedule }) => result`, where `result` is `{ wake: false, note? }` or `{ wake: true, context }`.
+`today` is the date in the host's time zone, so a script never reads a UTC date by mistake.
+`mcp.call(server, tool, args)` returns the MCP tool result and `mcp.json(server, tool, args)` its structured content or its first text content parsed as JSON; a tool error throws.
+A throw, a wrong answer, or a timeout wakes the turn with the error.
+The runner's `describe` tells the model this contract and what it may call, through `schedule_list`.
+
 ## Development and verification
 
 From the pi-roundtable repository root:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable-sandbox",
-	"version": "0.7.10",
+	"version": "0.7.11",
 	"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.2",
 		"discord.js": "14.27.0",
-		"pi-roundtable": "0.7.10",
+		"pi-roundtable": "0.7.11",
 		"typebox": "1.3.34",
 		"typescript": "7.0.2"
 	}

package/src/container-driver.ts

@@ -17,6 +17,10 @@ export interface ContainerSpec {
 	memoryMb?: number;
 	cpus?: number;
 	pids?: number;
+	/** Runs this command instead of the image's own, such as a precheck script's runner. */
+	entrypoint?: readonly string[];
+	/** Mounts the workspace read-only, for a run that may write nothing to the host. */
+	workspaceReadOnly?: boolean;
 }
 export interface ContainerDriver {
 	run(
@@ -64,6 +68,15 @@ export function containerRunArgs(spec: ContainerSpec): string[] {
 		pids < 8
 	)
 		throw new Error("invalid resource limits");
+	const [command, ...args] = spec.entrypoint ?? [];
+	if (
+		spec.entrypoint &&
+		(!command ||
+			spec.entrypoint.some(
+				(part) => !part || part.startsWith("-") || /[\0\r\n]/.test(part),
+			))
+	)
+		throw new Error("invalid entrypoint");
 	return [
 		"run",
 		"--rm",
@@ -99,10 +112,12 @@ export function containerRunArgs(spec: ContainerSpec): string[] {
 		"--mount",
 		`type=bind,src=${spec.runDir},dst=/broker,readonly,bind-propagation=rprivate`,
 		"--mount",
-		`type=bind,src=${spec.workspaceDir},dst=/workspace,bind-propagation=rprivate`,
+		`type=bind,src=${spec.workspaceDir},dst=/workspace,${spec.workspaceReadOnly ? "readonly," : ""}bind-propagation=rprivate`,
 		"--env",
 		"HOME=/tmp/home",
+		...(command ? ["--entrypoint", command] : []),
 		spec.image,
+		...args,
 	];
 }
 
@@ -117,6 +132,30 @@ export class DockerContainerDriver implements ContainerDriver {
 		turn: SandboxTurn,
 		signal: AbortSignal,
 	): Promise<SandboxReply> {
+		const output = await this.exec(spec, JSON.stringify(turn), signal, {
+			stdoutBytes: 2 * 1024 * 1024,
+		});
+		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 };
+	}
+
+	/**
+	 * Runs one sealed container with `input` on its stdin and returns its stdout, bounded; a
+	 * nonzero exit or an abort throws, and the container is force-removed either way.
+	 */
+	async exec(
+		spec: ContainerSpec,
+		input: string,
+		signal: AbortSignal,
+		limits: { stdoutBytes: number },
+	): Promise<string> {
 		// Canonical paths prevent symlinks in operator configuration selecting a different mount.
 		const args = containerRunArgs({
 			...spec,
@@ -133,24 +172,16 @@ export class DockerContainerDriver implements ContainerDriver {
 		const abort = () => child.kill("SIGKILL");
 		signal.addEventListener("abort", abort, { once: true });
 		try {
-			child.stdin.write(JSON.stringify(turn));
+			child.stdin.write(input);
 			child.stdin.end();
 			const [output, , code] = await Promise.all([
-				boundedText(child.stdout, 2 * 1024 * 1024),
+				boundedText(child.stdout, limits.stdoutBytes),
 				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 };
+			return output;
 		} finally {
 			signal.removeEventListener("abort", abort);
 			child.kill("SIGKILL");

package/src/index.ts

@@ -97,6 +97,15 @@ export {
 	type SandboxService,
 	sandbox,
 } from "./plugin.ts";
+export {
+	PRECHECK_ENTRYPOINT,
+	type PrecheckContainerDriver,
+	type PrecheckMcpServer,
+	type PrecheckScriptRunnerOptions,
+	type PrecheckWorkerInput,
+	precheckBroker,
+	precheckScriptRunner,
+} from "./precheck-runner.ts";
 export type { SandboxReply, SandboxTurn, ToolSpec } from "./protocol.ts";
 export {
 	type ResearchTools,

package/src/precheck-runner.ts

@@ -0,0 +1,401 @@
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import type {
+	PrecheckResult,
+	PrecheckScope,
+	PrecheckScriptContext,
+	PrecheckScriptRunner,
+} from "pi-roundtable";
+import { listenBroker } from "./broker.ts";
+import {
+	type ContainerSpec,
+	DockerContainerDriver,
+} from "./container-driver.ts";
+import { boundedText, DUMMY_KEY, isRecord } from "./protocol.ts";
+
+/** An MCP server a precheck script may call, with only the listed tools. */
+export interface PrecheckMcpServer {
+	/** What the script calls it by, `mcp.call(name, tool, args)`: letters, digits, `_`, `-`. */
+	name: string;
+	/** A fixed Streamable HTTP endpoint answering a single `tools/call` with JSON or one SSE event. */
+	url: string;
+	/** The tools the script may call; every other method and tool is refused. */
+	tools: readonly string[];
+	/** The bearer credential, read on each call on the host; never sent to the container. */
+	token?: () => string | undefined | Promise<string | undefined>;
+}
+
+/** Runs one sealed container: its stdin is `input`, and its bounded stdout comes back. */
+export interface PrecheckContainerDriver {
+	exec(
+		spec: ContainerSpec,
+		input: string,
+		signal: AbortSignal,
+		limits: { stdoutBytes: number },
+	): Promise<string>;
+}
+
+export interface PrecheckScriptRunnerOptions {
+	/** An image with Bun and this package installed, such as the Pi sandbox image. */
+	image: string;
+	/** A dedicated, short host directory for each run's broker socket and empty workspace. */
+	runRoot: string;
+	/** The non-root host user the container runs as; it owns `runRoot`. */
+	uid: number;
+	gid: number;
+	/**
+	 * The MCP servers and tools a script for this scope may call: never more than the schedule's
+	 * agent can use itself. An empty list leaves the script no way out of its container.
+	 */
+	grant(
+		scope: PrecheckScope,
+	): readonly PrecheckMcpServer[] | Promise<readonly PrecheckMcpServer[]>;
+	/** The container's command; default the package's worker in the Pi image's layout. */
+	entrypoint?: readonly string[];
+	/** How long a script may run; default 60 seconds. */
+	timeoutMs?: number;
+	/** MCP calls one run may make, refused ones included; default 16. */
+	maxCalls?: number;
+	/** Allow cleartext MCP endpoints, for a server on the same host only. */
+	allowHttpMcp?: boolean;
+	/** The container's limits; default 256 MiB, one CPU, 32 processes. */
+	limits?: { memoryMb?: number; cpus?: number; pids?: number };
+	/** Replaceable in tests. */
+	driver?: PrecheckContainerDriver;
+	fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
+}
+
+/** Where the Pi sandbox image keeps this package's worker. */
+export const PRECHECK_ENTRYPOINT = Object.freeze([
+	"bun",
+	"/app/node_modules/pi-roundtable-sandbox/worker/precheck-main.ts",
+]);
+
+/** What the worker reads on its stdin. */
+export interface PrecheckWorkerInput {
+	script: string;
+	firedAt: string;
+	timeZone: string;
+	today: string;
+	schedule: { id: number; title: string };
+	servers: { name: string; tools: string[] }[];
+}
+
+const SERVER_NAME = /^[a-zA-Z0-9_-]{1,100}$/;
+const RESPONSE_BYTES = 1024 * 1024;
+
+function checkServers(
+	servers: readonly PrecheckMcpServer[],
+	allowHttp: boolean,
+): void {
+	const names = new Set<string>();
+	for (const server of servers) {
+		if (!SERVER_NAME.test(server.name) || names.has(server.name))
+			throw new Error("invalid or repeated precheck MCP server name");
+		names.add(server.name);
+		let url: URL;
+		try {
+			url = new URL(server.url);
+		} catch {
+			throw new Error("invalid precheck MCP endpoint");
+		}
+		if (
+			!(url.protocol === "https:" || (allowHttp && url.protocol === "http:")) ||
+			url.username ||
+			url.password ||
+			url.hash
+		)
+			throw new Error("precheck MCP endpoints must be credential-free HTTPS");
+		if (
+			!Array.isArray(server.tools) ||
+			server.tools.some(
+				(tool) => typeof tool !== "string" || !/^[\w.-]{1,128}$/.test(tool),
+			)
+		)
+			throw new Error("invalid precheck MCP tool list");
+	}
+}
+
+/**
+ * Whether a parsed answer carries the credential: in any key or string, also inside a string
+ * holding JSON (as MCP text content does), plainly or base64-encoded. This catches an upstream
+ * that echoes the credential; the grant must still name only upstreams the host trusts.
+ */
+function carries(value: unknown, secret: string, depth = 0): boolean {
+	if (depth > 64) return true;
+	const forms = [
+		secret,
+		Buffer.from(secret).toString("base64"),
+		Buffer.from(secret).toString("base64url"),
+	];
+	if (typeof value === "string") {
+		if (forms.some((form) => value.includes(form))) return true;
+		const trimmed = value.trim();
+		if (!/^[[{"]/.test(trimmed)) return false;
+		try {
+			return carries(JSON.parse(trimmed), secret, depth + 1);
+		} catch {
+			return false;
+		}
+	}
+	if (Array.isArray(value))
+		return value.some((item) => carries(item, secret, depth + 1));
+	if (isRecord(value))
+		return Object.entries(value).some(
+			([key, item]) =>
+				forms.some((form) => key.includes(form)) ||
+				carries(item, secret, depth + 1),
+		);
+	return false;
+}
+
+/** The JSON-RPC message of an answer: the body, or an SSE answer's last `data:` event that parses. */
+function jsonRpcMessage(
+	text: string,
+	eventStream: boolean,
+): Record<string, unknown> | undefined {
+	const parsed = (raw: string): Record<string, unknown> | undefined => {
+		try {
+			const value: unknown = JSON.parse(raw);
+			return isRecord(value) ? value : undefined;
+		} catch {
+			return undefined;
+		}
+	};
+	if (!eventStream) return parsed(text);
+	// An event's `data:` lines join with newlines; a blank line ends the event.
+	let found: Record<string, unknown> | undefined;
+	let data: string[] = [];
+	for (const line of [...text.split(/\r?\n/), ""]) {
+		if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
+		else if (line === "" && data.length) {
+			found = parsed(data.join("\n")) ?? found;
+			data = [];
+		}
+	}
+	return found;
+}
+
+/**
+ * The broker of one precheck run: only `POST /mcp/<server>` with a single `tools/call` of a
+ * granted tool, within the call budget. The host inserts the credential and checks nothing of
+ * it comes back.
+ */
+export function precheckBroker(options: {
+	servers: readonly PrecheckMcpServer[];
+	signal: AbortSignal;
+	maxCalls: number;
+	fetchImpl?: (url: string, init: RequestInit) => Promise<Response>;
+}): (request: Request) => Promise<Response> {
+	let remaining = options.maxCalls;
+	let active = false;
+	return async (request) => {
+		let url: URL;
+		try {
+			url = new URL(request.url);
+		} catch {
+			return new Response("invalid URL", { status: 400 });
+		}
+		const server = url.pathname.startsWith("/mcp/")
+			? options.servers.find((s) => s.name === url.pathname.slice(5))
+			: undefined;
+		const auth = request.headers.get("authorization");
+		if (
+			request.method !== "POST" ||
+			url.search ||
+			!server ||
+			(auth !== null && auth !== `Bearer ${DUMMY_KEY}`)
+		)
+			return new Response("not found", { status: 404 });
+		if (options.signal.aborted)
+			return new Response("run ended", { status: 410 });
+		if (active) return new Response("one call at a time", { status: 409 });
+		if (remaining <= 0)
+			return new Response("call budget exhausted", { status: 429 });
+		active = true;
+		remaining--;
+		let secret = "";
+		try {
+			const body: unknown = JSON.parse(
+				await boundedText(request.body, 64 * 1024),
+			);
+			const params = isRecord(body) ? body.params : undefined;
+			if (
+				!isRecord(body) ||
+				body.method !== "tools/call" ||
+				!isRecord(params) ||
+				typeof params.name !== "string" ||
+				!server.tools.includes(params.name) ||
+				!(params.arguments === undefined || isRecord(params.arguments))
+			)
+				return new Response("MCP method or tool refused", { status: 403 });
+			secret = (await server.token?.()) ?? "";
+			const upstream = await (options.fetchImpl ?? fetch)(server.url, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"content-type": "application/json",
+					accept: "application/json, text/event-stream",
+					...(secret ? { authorization: `Bearer ${secret}` } : {}),
+				},
+				body: JSON.stringify({
+					jsonrpc: "2.0",
+					id: 1,
+					method: "tools/call",
+					params: { name: params.name, arguments: params.arguments ?? {} },
+				}),
+				signal: AbortSignal.any([options.signal, request.signal]),
+			});
+			const text = await boundedText(upstream.body, RESPONSE_BYTES);
+			if (!upstream.ok)
+				return new Response("upstream refused", { status: 502 });
+			if (secret && text.includes(secret))
+				return new Response("credential reflected", { status: 502 });
+			const message = jsonRpcMessage(
+				text,
+				(upstream.headers.get("content-type") ?? "").includes(
+					"text/event-stream",
+				),
+			);
+			if (!message)
+				return new Response("upstream returned no JSON-RPC message", {
+					status: 502,
+				});
+			if (secret && carries(message, secret))
+				return new Response("credential reflected", { status: 502 });
+			// Only the JSON-RPC message leaves: no upstream headers, cookies, or redirects.
+			return Response.json(message);
+		} catch {
+			// Never expose upstream URLs, headers, credentials, or exception text.
+			return new Response("broker call failed", { status: 502 });
+		} finally {
+			active = false;
+		}
+	};
+}
+
+/** What a script for a scope is told: the contract, and the servers and tools it may call. */
+function guide(servers: readonly PrecheckMcpServer[]): string {
+	const reach =
+		servers.length === 0
+			? "Scripts for this schedule can call no MCP server, so they can only decide from the date and time."
+			: `Scripts for this schedule may call only these MCP servers and tools:\n${servers.map((s) => `- ${s.name}: ${s.tools.join(", ")}`).join("\n")}`;
+	return [
+		"Write `export default async ({ mcp, firedAt, timeZone, today, schedule }) => result`.",
+		"`result` is `{ wake: false, note? }` to skip the turn (the note, if any, is posted in small text) or `{ wake: true, context }` to wake you with `context`. Anything else, a throw, or running too long wakes you with the error.",
+		"`today` is the date in the host's time zone (YYYY-MM-DD); pass it to tools instead of computing dates in UTC. `firedAt` is a Date and `timeZone` an IANA zone.",
+		"Await each call before making the next; calls do not run in parallel. console output is discarded; only the returned result counts.",
+		"`await mcp.call(server, tool, args)` returns the MCP tool result; `await mcp.json(server, tool, args)` returns its structured content, or its first text content parsed as JSON. A tool error throws.",
+		"The script runs in a container with no network, no files of the host, and no credentials; it reaches only the tools below.",
+		reach,
+	].join("\n");
+}
+
+/**
+ * Runs agents' precheck scripts in a sealed container, one per run: no network, a read-only
+ * root, all capabilities dropped, a non-root user, and an empty workspace. Its only way out is a
+ * per-run broker that forwards `tools/call` of the tools `grant` allows. Register it with
+ * `services.get(PRECHECKS).useScriptRunner(precheckScriptRunner({ ... }))`.
+ */
+export function precheckScriptRunner(
+	options: PrecheckScriptRunnerOptions,
+): PrecheckScriptRunner {
+	const driver = options.driver ?? new DockerContainerDriver();
+	const maxCalls = options.maxCalls ?? 16;
+	if (!Number.isSafeInteger(maxCalls) || maxCalls < 1 || maxCalls > 100)
+		throw new Error("invalid precheck MCP call budget");
+	const grant = async (scope: PrecheckScope) => {
+		const servers = await options.grant(scope);
+		checkServers(servers, options.allowHttpMcp ?? false);
+		return servers;
+	};
+	return {
+		...(options.timeoutMs === undefined
+			? {}
+			: { timeoutMs: options.timeoutMs }),
+		describe: async (scope) => guide(await grant(scope)),
+		run: async (script, context) => runOne(script, context),
+	};
+
+	async function runOne(
+		script: string,
+		context: PrecheckScriptContext,
+	): Promise<PrecheckResult> {
+		const { schedule, signal } = context;
+		const servers = await grant({
+			channel: schedule.channel,
+			target: schedule.target,
+			tier: schedule.createdTier,
+		});
+		const dirs: string[] = [];
+		let listener: Awaited<ReturnType<typeof listenBroker>> | undefined;
+		try {
+			const runDir = mkdtempSync(join(options.runRoot, "precheck-"));
+			dirs.push(runDir);
+			// Mounted read-only and left empty: a script can write only its container's bounded /tmp.
+			const workspaceDir = mkdtempSync(join(options.runRoot, "precheck-ws-"));
+			dirs.push(workspaceDir);
+			const socket = join(runDir, "broker.sock");
+			if (socket.length > 100) throw new Error("broker socket path too long");
+			listener = await listenBroker(
+				socket,
+				precheckBroker({
+					servers,
+					signal,
+					maxCalls,
+					...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+				}),
+			);
+			const input: PrecheckWorkerInput = {
+				script,
+				firedAt: context.firedAt.toISOString(),
+				timeZone: context.timeZone,
+				today: context.today,
+				schedule: { id: schedule.id, title: schedule.title },
+				servers: servers.map(({ name, tools }) => ({
+					name,
+					tools: [...tools],
+				})),
+			};
+			const output = await driver.exec(
+				{
+					name: `roundtable-precheck-${schedule.id}-${randomUUID().slice(0, 8)}`,
+					image: options.image,
+					runDir,
+					workspaceDir,
+					uid: options.uid,
+					gid: options.gid,
+					memoryMb: options.limits?.memoryMb ?? 256,
+					cpus: options.limits?.cpus ?? 1,
+					pids: options.limits?.pids ?? 32,
+					entrypoint: options.entrypoint ?? PRECHECK_ENTRYPOINT,
+					workspaceReadOnly: true,
+				},
+				JSON.stringify(input),
+				signal,
+				{ stdoutBytes: 64 * 1024 },
+			);
+			const answer: unknown = JSON.parse(output);
+			if (!isRecord(answer) || typeof answer.ok !== "boolean")
+				throw new Error("the precheck worker answered nothing it could read");
+			if (!answer.ok)
+				throw new Error(
+					typeof answer.error === "string"
+						? answer.error.slice(0, 1000)
+						: "the script failed",
+				);
+			// The core checks the result's shape; a wrong one wakes the turn with what it was.
+			return answer.result as PrecheckResult;
+		} finally {
+			await listener?.stop(true);
+			// A cleanup failure is logged by nobody but must not replace the script's answer.
+			for (const dir of dirs)
+				try {
+					rmSync(dir, { recursive: true, force: true });
+				} catch {
+					// Left for the operator; runRoot is dedicated to these runs.
+				}
+		}
+	}
+}

package/worker/Dockerfile

@@ -1,6 +1,6 @@
 FROM oven/bun:1.4.2-alpine
 WORKDIR /app
 COPY src/protocol.ts /app/src/protocol.ts
-COPY worker/main.ts worker/agent.ts worker/memory.ts worker/transport.ts /app/worker/
+COPY worker/main.ts worker/agent.ts worker/memory.ts worker/transport.ts worker/precheck-main.ts /app/worker/
 USER 1000:1000
 ENTRYPOINT ["bun", "/app/worker/main.ts"]

package/worker/precheck-main.ts

@@ -0,0 +1,147 @@
+// Runs one schedule's precheck script inside its sealed container and prints its answer.
+// The script is untrusted: the container, not this file, is the boundary.
+import { randomUUID } from "node:crypto";
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BROKER_PATH, boundedText, isRecord } from "../src/protocol.ts";
+import { unixBrokerRequest } from "./transport.ts";
+
+interface Input {
+	script: string;
+	firedAt: string;
+	timeZone: string;
+	today: string;
+	schedule: { id: number; title: string };
+	servers: { name: string; tools: string[] }[];
+}
+
+function isInput(value: unknown): value is Input {
+	return (
+		isRecord(value) &&
+		typeof value.script === "string" &&
+		typeof value.firedAt === "string" &&
+		typeof value.timeZone === "string" &&
+		typeof value.today === "string" &&
+		isRecord(value.schedule) &&
+		Array.isArray(value.servers)
+	);
+}
+
+const REFUSALS: Record<number, string> = {
+	403: "that server or tool is not granted to this script",
+	404: "that server is not granted to this script",
+	410: "the run ended",
+	409: "the script made two MCP calls at once; await each before the next",
+	429: "the script made too many MCP calls",
+};
+
+/** The MCP calls a script makes, each through the host's broker. */
+function mcpClient(servers: Input["servers"]) {
+	const call = async (
+		server: string,
+		tool: string,
+		args: Record<string, unknown> = {},
+	): Promise<Record<string, unknown>> => {
+		const granted = servers.find((s) => s.name === server);
+		if (!granted?.tools.includes(tool))
+			throw new Error(`${server}/${tool} is not granted to this script`);
+		const { status, body } = await unixBrokerRequest(
+			`/mcp/${server}`,
+			{
+				jsonrpc: "2.0",
+				id: 1,
+				method: "tools/call",
+				params: { name: tool, arguments: args },
+			},
+			// Tests run the worker outside a container; there the host sets only HOME.
+			process.env.PRECHECK_BROKER_SOCKET ?? BROKER_PATH,
+		);
+		if (status !== 200)
+			throw new Error(
+				`${server}/${tool}: ${REFUSALS[status] ?? "the broker call failed"}`,
+			);
+		if (!isRecord(body)) throw new Error(`${server}/${tool}: no answer`);
+		if (isRecord(body.error))
+			throw new Error(`${server}/${tool}: ${String(body.error.message)}`);
+		const result = body.result;
+		if (!isRecord(result)) throw new Error(`${server}/${tool}: no result`);
+		if (result.isError === true)
+			throw new Error(`${server}/${tool}: ${firstText(result) ?? "failed"}`);
+		return result;
+	};
+	return {
+		call,
+		/** The result's structured content, or its first text content parsed as JSON (or as text). */
+		async json(
+			server: string,
+			tool: string,
+			args: Record<string, unknown> = {},
+		): Promise<unknown> {
+			const result = await call(server, tool, args);
+			if (result.structuredContent !== undefined)
+				return result.structuredContent;
+			const text = firstText(result);
+			if (text === undefined) return undefined;
+			try {
+				return JSON.parse(text);
+			} catch {
+				return text;
+			}
+		},
+	};
+}
+
+function firstText(result: Record<string, unknown>): string | undefined {
+	const content = Array.isArray(result.content) ? result.content : [];
+	const text = content.find(
+		(item): item is { text: string } =>
+			isRecord(item) && item.type === "text" && typeof item.text === "string",
+	);
+	return text?.text;
+}
+
+function message(error: unknown): string {
+	return (error instanceof Error ? error.message : String(error)).slice(
+		0,
+		1000,
+	);
+}
+
+/** Runs the script and returns what to print; never throws. */
+async function answer(): Promise<string> {
+	try {
+		const input: unknown = JSON.parse(
+			await boundedText(Bun.stdin.stream(), 64 * 1024),
+		);
+		if (!isInput(input)) throw new Error("invalid precheck input");
+		// stdout carries only the answer; whatever the script logs goes to stderr.
+		for (const level of ["log", "info", "debug", "warn"] as const)
+			console[level] = console.error;
+		const path = join(tmpdir(), `precheck-${randomUUID()}.mjs`);
+		await Bun.write(path, input.script);
+		let module: unknown;
+		try {
+			module = await import(path);
+		} finally {
+			await rm(path, { force: true });
+		}
+		const check = isRecord(module) ? module.default : undefined;
+		if (typeof check !== "function")
+			throw new Error("the script has no default export function");
+		const result: unknown = await check({
+			mcp: mcpClient(input.servers),
+			firedAt: new Date(input.firedAt),
+			timeZone: input.timeZone,
+			today: input.today,
+			schedule: input.schedule,
+		});
+		return JSON.stringify({ ok: true, result: result ?? null });
+	} catch (error) {
+		return JSON.stringify({ ok: false, error: message(error) });
+	}
+}
+
+// Exit once the answer is written, even if the script left timers or sockets behind.
+await Bun.write(Bun.stdout, await answer());
+process.exit(0);