pi-roundtable-sandbox 0.7.9 → 0.7.10

package/src/pi-container-driver.ts

@@ -14,6 +14,14 @@ export interface PiContainerSpec {
 	/** The host user that owns the mounted directories. */
 	uid: number;
 	gid: number;
+	/** Docker's log driver for the container; journald tagged `sandbox/<channel>` by default. */
+	log?: PiContainerLog;
+}
+
+/** A Docker log driver and its options, as `docker run --log-driver/--log-opt` takes them. */
+export interface PiContainerLog {
+	driver: string;
+	options?: Readonly<Record<string, string>>;
 }
 
 export type PiContainerState = "missing" | "running" | "stopped";
@@ -30,6 +38,16 @@ export interface PiContainerDriver {
 	ensureRunning(spec: PiContainerSpec): Promise<void>;
 	remove(name: string): Promise<void>;
 	status(name: string): Promise<PiContainerStatus>;
+	/** The container's last log lines, read before it is removed; empty when it is gone. */
+	logs?(name: string, lines: number): Promise<string>;
+}
+
+/** journald keeps a removed container's lines; the tag names the channel they came from. */
+export function defaultContainerLog(channel: string): PiContainerLog {
+	return {
+		driver: "journald",
+		options: { tag: `sandbox/${channel.replace(/[^\w.:/-]/g, "_")}` },
+	};
 }
 
 export const PI_LABEL_CHANNEL = "roundtable.sandbox.channel";
@@ -59,6 +77,17 @@ export function piContainerCreateBody(spec: PiContainerSpec): object {
 		if (!dir.startsWith("/") || dir === "/" || /[:,\r\n]/.test(dir))
 			throw new Error("Invalid mount path");
 	new Intl.DateTimeFormat("en-US", { timeZone: spec.timeZone ?? "UTC" });
+	const log = spec.log ?? defaultContainerLog(spec.channel);
+	if (
+		!/^[a-z0-9][a-z0-9_.-]{0,63}$/.test(log.driver) ||
+		Object.entries(log.options ?? {}).some(
+			([key, value]) =>
+				!/^[a-z0-9][a-z0-9_.-]{0,63}$/.test(key) ||
+				typeof value !== "string" ||
+				/[\r\n]/.test(value),
+		)
+	)
+		throw new Error("Invalid container log driver");
 	return {
 		Image: spec.image,
 		User: `${spec.uid}:${spec.gid}`,
@@ -96,13 +125,34 @@ export function piContainerCreateBody(spec: PiContainerSpec): object {
 			],
 			RestartPolicy: { Name: "unless-stopped" },
 			LogConfig: {
-				Type: "local",
-				Config: { "max-size": "10m", "max-file": "2" },
+				Type: log.driver,
+				Config: { ...log.options },
 			},
 		},
 	};
 }
 
+/**
+ * A container without a TTY sends its log as frames: one byte naming the stream, three zero bytes,
+ * a big-endian length, then that many bytes. Text that is not framed is returned as it came.
+ */
+export function demuxDockerLog(data: Uint8Array): string {
+	const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+	const parts: Uint8Array[] = [];
+	let at = 0;
+	while (at + 8 <= data.length) {
+		const stream = data[at] ?? 255;
+		if (stream > 2 || data[at + 1] || data[at + 2] || data[at + 3])
+			return new TextDecoder().decode(data);
+		const size = view.getUint32(at + 4);
+		parts.push(data.subarray(at + 8, at + 8 + size));
+		at += 8 + size;
+	}
+	if (at !== data.length && parts.length === 0)
+		return new TextDecoder().decode(data);
+	return parts.map((part) => new TextDecoder().decode(part)).join("");
+}
+
 interface InspectBody {
 	Config?: { Image?: string; Labels?: Record<string, string> };
 	State?: { Running?: boolean };
@@ -112,11 +162,19 @@ interface InspectBody {
 export class PiDockerContainerDriver implements PiContainerDriver {
 	readonly #socket: string;
 
+	readonly #log: ((channel: string) => PiContainerLog) | undefined;
+
 	constructor(
 		socket = "/var/run/docker.sock",
 		readonly labelProfile = PI_LABEL_PROFILE,
+		/** The log driver every container gets; journald tagged `sandbox/<channel>` by default. */
+		options: {
+			log?: PiContainerLog | ((channel: string) => PiContainerLog);
+		} = {},
 	) {
 		this.#socket = socket;
+		const { log } = options;
+		this.#log = typeof log === "function" ? log : log && (() => log);
 	}
 
 	async ensureRunning(spec: PiContainerSpec): Promise<void> {
@@ -132,7 +190,9 @@ export class PiDockerContainerDriver implements PiContainerDriver {
 		await this.#call(
 			"POST",
 			`/containers/create?name=${encodeURIComponent(spec.name)}`,
-			piContainerCreateBody(spec),
+			piContainerCreateBody(
+				this.#log ? { ...spec, log: this.#log(spec.channel) } : spec,
+			),
 		);
 		await this.#call(
 			"POST",
@@ -149,6 +209,17 @@ export class PiDockerContainerDriver implements PiContainerDriver {
 		);
 	}
 
+	async logs(name: string, lines: number): Promise<string> {
+		const response = await this.#call(
+			"GET",
+			`/containers/${encodeURIComponent(name)}/logs?stdout=1&stderr=1&tail=${Math.max(1, Math.floor(lines))}`,
+			undefined,
+			[404],
+		);
+		if (response.status === 404) return "";
+		return demuxDockerLog(new Uint8Array(await response.arrayBuffer()));
+	}
+
 	async status(name: string): Promise<PiContainerStatus> {
 		const response = await this.#call(
 			"GET",

package/src/pi-protocol.ts

@@ -78,6 +78,124 @@ export interface PiTurnContext {
 export interface PiMcpDiscovery {
 	servers: { name: string; tools: string[] }[];
 }
+/** What the worker learns from the host at startup; `compaction` is absent when the host has no compactor. */
+export interface PiWorkerConfig {
+	compaction?: { engine: string };
+}
+/** The JSON of one Pi `AgentMessage` from the worker's session. */
+export type PiCompactMessage = { role: string } & Record<string, unknown>;
+/** The worker's compaction preparation, sent to the host's compactor. */
+export interface PiCompactRequest {
+	/** What triggered the compaction: a manual compact, the context threshold, or an overflow. */
+	reason: "manual" | "threshold" | "overflow";
+	tokensBefore: number;
+	/** The first session entry the compaction keeps; a compaction must keep the same one. */
+	firstKeptEntryId: string;
+	/** Whether the cut falls inside a turn, so `turnPrefixMessages` holds that turn's start. */
+	isSplitTurn: boolean;
+	messagesToSummarize: PiCompactMessage[];
+	turnPrefixMessages: PiCompactMessage[];
+	/** The messages from `firstKeptEntryId` on, which stay in the context. */
+	keptMessages: PiCompactMessage[];
+	previousSummary?: string;
+	customInstructions?: string;
+	/** Files only read, and files written or edited, in the summarized messages. */
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+/** A compaction the host's compactor wrote, shaped as Pi's `CompactionResult`. */
+export interface PiCompaction {
+	summary: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	estimatedTokensAfter?: number;
+	details?: unknown;
+}
+/** The host's answer: a compaction, or a fallback to Pi's own summary with its reason. */
+export type PiCompactResponse =
+	| { ok: true; compaction: PiCompaction }
+	| { ok: false; fallback: string };
+/** What the worker tells the host about its compactions, so the host logs them per channel. */
+export type PiCompactionReport =
+	| {
+			type: "bypass";
+			/** Why the hard ceiling skipped the host's compactor for Pi's summary. */
+			reason: string;
+			tokensBefore: number;
+	  }
+	| {
+			type: "end";
+			reason: PiCompactRequest["reason"];
+			aborted: boolean;
+			willRetry: boolean;
+			/** Absent when the compaction failed. */
+			engine?: "extension" | "pi";
+			tokensBefore?: number;
+			tokensAfter?: number;
+			nextCompactionAt?: number;
+			error?: string;
+	  };
+const COMPACT_REASONS = ["manual", "threshold", "overflow"];
+function isMessageList(value: unknown): value is PiCompactMessage[] {
+	return (
+		Array.isArray(value) &&
+		value.every((item) => isRecord(item) && typeof item.role === "string")
+	);
+}
+function isStringList(value: unknown): value is string[] {
+	return (
+		Array.isArray(value) && value.every((item) => typeof item === "string")
+	);
+}
+function isTokenCount(value: unknown): value is number {
+	return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+export function validateCompactRequest(
+	value: unknown,
+): asserts value is PiCompactRequest {
+	if (
+		!isRecord(value) ||
+		!COMPACT_REASONS.includes(value.reason as string) ||
+		!isTokenCount(value.tokensBefore) ||
+		typeof value.firstKeptEntryId !== "string" ||
+		value.firstKeptEntryId.length === 0 ||
+		value.firstKeptEntryId.length > 256 ||
+		typeof value.isSplitTurn !== "boolean" ||
+		!isMessageList(value.messagesToSummarize) ||
+		!isMessageList(value.turnPrefixMessages) ||
+		!isMessageList(value.keptMessages) ||
+		(value.previousSummary !== undefined &&
+			typeof value.previousSummary !== "string") ||
+		(value.customInstructions !== undefined &&
+			typeof value.customInstructions !== "string") ||
+		!isStringList(value.readFiles) ||
+		!isStringList(value.modifiedFiles)
+	)
+		throw new Error("Invalid compact request");
+}
+export function validateCompactionReport(
+	value: unknown,
+): asserts value is PiCompactionReport {
+	const valid =
+		isRecord(value) &&
+		(value.type === "bypass"
+			? typeof value.reason === "string" &&
+				value.reason.length <= 1000 &&
+				isTokenCount(value.tokensBefore)
+			: value.type === "end" &&
+				COMPACT_REASONS.includes(value.reason as string) &&
+				typeof value.aborted === "boolean" &&
+				typeof value.willRetry === "boolean" &&
+				(value.engine === undefined ||
+					value.engine === "extension" ||
+					value.engine === "pi") &&
+				[value.tokensBefore, value.tokensAfter, value.nextCompactionAt].every(
+					(count) => count === undefined || isTokenCount(count),
+				) &&
+				(value.error === undefined ||
+					(typeof value.error === "string" && value.error.length <= 10_000)));
+	if (!valid) throw new Error("Invalid compaction report");
+}
 export function isPiThinkingLevel(value: unknown): value is PiThinkingLevel {
 	return (
 		typeof value === "string" &&

package/src/pi-runtime.ts

@@ -14,9 +14,14 @@ import {
 } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { AgentRunError, type ChannelKey, type Logger } from "pi-roundtable";
-import { channelSegment } from "pi-roundtable/kit";
+import { channelSegment, scrubDiagnostic } from "pi-roundtable/kit";
 import { ownDirectory } from "./directory-file.ts";
-import { type PiBrokerOptions, PiSandboxBroker } from "./pi-broker.ts";
+import {
+	errorText,
+	PI_COMPACT_LIMITS,
+	type PiBrokerOptions,
+	PiSandboxBroker,
+} from "./pi-broker.ts";
 import {
 	type PiContainerDriver,
 	type PiContainerStatus,
@@ -129,17 +134,31 @@ export class PiSandboxRuntime {
 			)
 		)
 			throw new Error("Invalid container prefix");
-		for (const timeout of [
-			options.turnTimeoutMs ?? 600_000,
-			options.startTimeoutMs ?? 90_000,
-		])
+		const turnTimeoutMs = options.turnTimeoutMs ?? 600_000;
+		for (const timeout of [turnTimeoutMs, options.startTimeoutMs ?? 90_000])
 			if (!Number.isSafeInteger(timeout) || timeout < 1000 || timeout > 600_000)
 				throw new Error("Invalid runtime deadline");
+		// A compactor that runs out of time still leaves Pi's summary half the turn.
+		const compaction = options.compaction && {
+			...options.compaction,
+			timeoutMs:
+				options.compaction.timeoutMs ??
+				Math.max(
+					1000,
+					Math.min(PI_COMPACT_LIMITS.timeoutMs, Math.floor(turnTimeoutMs / 3)),
+				),
+		};
+		if (compaction && compaction.timeoutMs > turnTimeoutMs / 2)
+			throw new Error("The compactor's timeout must leave half the turn");
 		mkdirSync(options.partyDir, { recursive: true, mode: 0o700 });
 		const info = statSync(options.partyDir);
 		if (info.uid !== process.getuid?.() || (info.mode & 0o077) !== 0)
 			throw new Error("State directory must be private and host-owned");
-		this.#options = { ...options, partyDir: realpathSync(options.partyDir) };
+		this.#options = {
+			...options,
+			partyDir: realpathSync(options.partyDir),
+			...(compaction ? { compaction } : {}),
+		};
 		this.#driver =
 			options.driver ??
 			new PiDockerContainerDriver(undefined, options.labelProfile);
@@ -311,6 +330,22 @@ export class PiSandboxRuntime {
 		await Promise.all([...this.#brokers.values()].map((entry) => entry.stop()));
 		this.#brokers.clear();
 	}
+	/** The worker's last log lines, read before its container is removed, so they are not lost with it. */
+	async #logWorker(channel: ChannelKey, turnId: string): Promise<void> {
+		if (!this.#driver.logs) return;
+		try {
+			const lines = await this.#driver.logs(this.#name(channel), 200);
+			this.#options.logger.warn(
+				{ channel, turnId, lines: scrubDiagnostic(lines, 200_000) },
+				"sandbox worker log before removal",
+			);
+		} catch (error) {
+			this.#options.logger.warn(
+				{ channel, turnId, error: scrubDiagnostic(errorText(error)) },
+				"sandbox worker log unavailable",
+			);
+		}
+	}
 	async runTurn(turn: PiSandboxTurn): Promise<PiSandboxTurnResult> {
 		if (this.#active.has(turn.channel))
 			return { ok: false, error: new AgentRunError("Channel is busy") };
@@ -322,6 +357,10 @@ export class PiSandboxRuntime {
 			AbortSignal.timeout(this.#options.turnTimeoutMs ?? 600_000),
 		]);
 		signal.addEventListener("abort", () => controller.abort(), { once: true });
+		const timedOut = () =>
+			signal.aborted &&
+			signal.reason instanceof DOMException &&
+			signal.reason.name === "TimeoutError";
 		let release: (() => void) | undefined;
 		try {
 			signal.throwIfAborted();
@@ -372,20 +411,38 @@ export class PiSandboxRuntime {
 			});
 			const body = await entry.broker.execute(request, signal);
 			signal.throwIfAborted();
-			if (!body.ok) throw new Error("Worker turn failed");
+			if (!body.ok) throw new Error(`Worker turn failed: ${body.error}`);
 			validateReplyFiles(body.files);
 			const files = body.files.map((file) => ({
 				name: file.name,
 				data: Buffer.from(file.data, "base64"),
 			}));
 			return { ok: true, text: body.text, files };
-		} catch {
+		} catch (error) {
+			const failure = {
+				message: scrubDiagnostic(errorText(error), 4000),
+				timedOut: timedOut(),
+				cancelled: signal.aborted && !timedOut(),
+			};
+			this.#options.logger.error(
+				{ channel: turn.channel, turnId: turn.turnId, ...failure },
+				"sandbox turn failed",
+			);
 			// A timed-out Pi session must not keep consuming broker tools or corrupt the next turn.
 			if (signal.aborted) {
 				await this.#starts.get(turn.channel)?.catch(() => {});
+				await this.#logWorker(turn.channel, turn.turnId);
 				await this.#driver.remove(this.#name(turn.channel));
 			}
-			return { ok: false, error: new AgentRunError("Sandbox turn failed") };
+			return {
+				ok: false,
+				error: new AgentRunError(
+					failure.timedOut
+						? "Sandbox turn timed out"
+						: `Sandbox turn failed: ${failure.message}`,
+					{ cause: error },
+				),
+			};
 		} finally {
 			controller.abort();
 			release?.();

package/worker/pi-compaction.ts

@@ -0,0 +1,225 @@
+/**
+ * The worker session's compaction: the host's tiers, and the host's compactor reached over the broker.
+ */
+import type {
+	AgentSession,
+	AgentSessionEvent,
+	ExtensionFactory,
+	SessionBeforeCompactEvent,
+	SessionBeforeCompactResult,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import {
+	type CompactionHistory,
+	CompactionTiers,
+	compactionEngine,
+} from "pi-roundtable/kit";
+import type {
+	PiCompactionReport,
+	PiCompactMessage,
+	PiCompactRequest,
+	PiCompactResponse,
+	PiWorkerConfig,
+} from "../src/pi-protocol.ts";
+
+type CompactionEnd = Extract<AgentSessionEvent, { type: "compaction_end" }>;
+export type WorkerLog = (msg: string, fields?: Record<string, unknown>) => void;
+
+export interface WorkerCompactionOptions {
+	/** The session's entries, for the tiers' loop guard. */
+	history: CompactionHistory;
+	contextWindow(provider: string, id: string): number | undefined;
+	/** What the host told the worker at startup; no `compaction` means no host compactor. */
+	config: PiWorkerConfig;
+	/** The broker's Unix socket. */
+	socket: string;
+	log: WorkerLog;
+}
+
+/** The request the host's compactor reads: Pi's preparation, with the messages it keeps. */
+export function compactRequest(
+	event: SessionBeforeCompactEvent,
+): PiCompactRequest {
+	const { preparation } = event;
+	const start = event.branchEntries.findIndex(
+		(entry) => entry.id === preparation.firstKeptEntryId,
+	);
+	const keptMessages =
+		start < 0
+			? []
+			: event.branchEntries
+					.slice(start)
+					.flatMap((entry) =>
+						entry.type === "message" ? [entry.message] : [],
+					);
+	const { read, written, edited } = preparation.fileOps;
+	const modified = new Set([...written, ...edited]);
+	return {
+		reason: event.reason,
+		tokensBefore: preparation.tokensBefore,
+		firstKeptEntryId: preparation.firstKeptEntryId,
+		isSplitTurn: preparation.isSplitTurn,
+		messagesToSummarize: preparation.messagesToSummarize as PiCompactMessage[],
+		turnPrefixMessages: preparation.turnPrefixMessages as PiCompactMessage[],
+		keptMessages: keptMessages as PiCompactMessage[],
+		...(preparation.previousSummary === undefined
+			? {}
+			: { previousSummary: preparation.previousSummary }),
+		...(event.customInstructions === undefined
+			? {}
+			: { customInstructions: event.customInstructions }),
+		readFiles: [...read].filter((path) => !modified.has(path)).sort(),
+		modifiedFiles: [...modified].sort(),
+	};
+}
+
+/**
+ * Compacts as the host's own sessions do: large windows at the soft threshold through the host's
+ * compactor, past the hard ceiling through Pi's summary, which reaches the model over the broker.
+ */
+export class WorkerCompaction {
+	readonly #options: WorkerCompactionOptions;
+	readonly #tiers: CompactionTiers;
+	readonly #pending = new Set<Promise<void>>();
+
+	constructor(options: WorkerCompactionOptions) {
+		this.#options = options;
+		this.#tiers = new CompactionTiers(
+			options.history,
+			options.contextWindow,
+			options.config.compaction?.engine,
+		);
+	}
+
+	/** Pi's settings, with each model's reserve set so it compacts at its tier. */
+	settings(): SettingsManager {
+		return this.#tiers.settings();
+	}
+
+	/** The host compactor's handler, held back by the tiers; none when the host has no compactor. */
+	extensions(): { name: string; factory: ExtensionFactory }[] {
+		if (!this.#options.config.compaction) return [];
+		const handler: ExtensionFactory = (pi) => {
+			pi.on("session_before_compact", (event) => this.#compact(event));
+		};
+		return [
+			{
+				name: "host-compaction",
+				factory: this.#tiers.wrapCompactor(handler, (bypass) => {
+					this.#options.log("compaction skips the host compactor", bypass);
+					void this.#report({ type: "bypass", ...bypass });
+				}),
+			},
+		];
+	}
+
+	/** Logs a finished compaction and reports it to the host, which logs it for the channel. */
+	async ended(event: CompactionEnd, session: AgentSession): Promise<void> {
+		const { result } = event;
+		const { model, settingsManager } = session;
+		const report: PiCompactionReport = result
+			? {
+					type: "end",
+					reason: event.reason,
+					aborted: event.aborted,
+					willRetry: event.willRetry,
+					engine: compactionEngine(
+						result.details,
+						this.#options.config.compaction?.engine,
+					),
+					tokensBefore: result.tokensBefore,
+					...(result.estimatedTokensAfter === undefined
+						? {}
+						: { tokensAfter: result.estimatedTokensAfter }),
+					...(model
+						? {
+								nextCompactionAt:
+									model.contextWindow -
+									settingsManager.getCompactionSettings(model).reserveTokens,
+							}
+						: {}),
+				}
+			: {
+					type: "end",
+					reason: event.reason,
+					aborted: event.aborted,
+					willRetry: event.willRetry,
+					...(event.errorMessage === undefined
+						? {}
+						: { error: event.errorMessage.slice(0, 10_000) }),
+				};
+		const { type: _type, ...fields } = report;
+		this.#options.log(
+			result ? "conversation compacted" : "compaction failed",
+			fields,
+		);
+		await this.#report(report);
+	}
+
+	async #compact(
+		event: SessionBeforeCompactEvent,
+	): Promise<SessionBeforeCompactResult | undefined> {
+		const { log } = this.#options;
+		try {
+			// Local Unix-socket transport; no TCP connection or DNS lookup is made.
+			// nosemgrep: typescript.react.security.react-insecure-request.react-insecure-request
+			const response = await fetch("http://broker/compaction/compact", {
+				unix: this.#options.socket,
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(compactRequest(event)),
+				signal: event.signal,
+			});
+			if (!response.ok) {
+				await response.body?.cancel();
+				log("compaction falls back to Pi's summary", {
+					fallback: `the broker answered ${response.status}`,
+				});
+				return undefined;
+			}
+			const answer = (await response.json()) as PiCompactResponse;
+			if (!answer.ok) {
+				log("compaction falls back to Pi's summary", {
+					fallback: answer.fallback,
+				});
+				return undefined;
+			}
+			return { compaction: answer.compaction };
+		} catch (error) {
+			log("compaction falls back to Pi's summary", {
+				fallback: `the compact request failed: ${String(error)}`,
+			});
+			return undefined;
+		}
+	}
+
+	/** Waits for the reports still on their way, so they reach the host while the turn is bound. */
+	async settled(): Promise<void> {
+		await Promise.allSettled([...this.#pending]);
+	}
+
+	#report(report: PiCompactionReport): Promise<void> {
+		const sending = this.#send(report).finally(() =>
+			this.#pending.delete(sending),
+		);
+		this.#pending.add(sending);
+		return sending;
+	}
+
+	async #send(report: PiCompactionReport): Promise<void> {
+		try {
+			// Local Unix-socket transport; no TCP connection or DNS lookup is made.
+			// nosemgrep: typescript.react.security.react-insecure-request.react-insecure-request
+			const response = await fetch("http://broker/compaction/report", {
+				unix: this.#options.socket,
+				method: "POST",
+				headers: { "content-type": "application/json" },
+				body: JSON.stringify(report),
+				signal: AbortSignal.timeout(5000),
+			});
+			await response.body?.cancel();
+		} catch (error) {
+			this.#options.log("compaction report failed", { error: String(error) });
+		}
+	}
+}