pi-roundtable-sandbox 0.7.8 → 0.7.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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.
+- A failed `runTurn` keeps its cause (`AgentRunError` message and `cause`, whether it timed out) and logs it; the broker logs upstream failures with channel, status, latency and the error body; a timed-out worker's last 200 log lines are logged before its container is removed (`PiContainerDriver.logs`).
+- Behavior change: Pi containers log to journald tagged `sandbox/<channel>` by default, instead of two 10 MiB `local` files, so the Docker daemon must run with journald (pass `PiDockerContainerDriver` a `log` option for another driver) (`PiContainerSpec.log`, `PiDockerContainerDriver` option `log`, `defaultContainerLog`), and the worker logs model, broker, tool and compaction failures.
+
 ## 0.7.5
 
 - `ScopedSandboxDelegator` limits a title to 200 characters by default again, and accepts `maxTitleChars`, `maxReportChars` and `diagnosticChars`.

package/README.md

@@ -226,7 +226,8 @@ Other model transports are not implicitly proxied by this broker.
 | `timeZone` | Explicit worker time zone; default UTC. |
 | `containerPrefix`, `labelChannel`, `labelProfile` | Operator compatibility names for existing containers, not guest data. |
 | `driver` | Trusted local Docker driver or offline fixture; no remote bind mounts. |
-| `logger` | Host logger; package failures avoid credentials and upstream payloads. |
+| `logger` | Host logger: failed turns with their cause, upstream failures (channel, status, latency, error body cut to 2,000 characters with credentials masked), a timed-out worker's last 200 log lines, and every compaction. |
+| `compaction` | Optional host compactor (`PiCompactor`), see [Compaction](#compaction). |
 | `startTimeoutMs`, `turnTimeoutMs` | 1–600 seconds; defaults 90 and 600 seconds. |
 | `maxCalls`, `maxOutputTokens` | Default 128 credential-bearing calls and 128,000 output tokens per model call; configurable 1–1,000 calls and 1,025–200,000 tokens. |
 
@@ -238,6 +239,37 @@ Callbacks must still validate input and enforce per-person quotas, memory author
 Optional person/notes/moments tools can use an existing PostgreSQL store without copying the connection, schema, migration ledger or owner memory into the image.
 Schedules can be host tools with a declared channel-local background target and host-bound author; no scheduler is enabled automatically.
 
+### Compaction
+
+Worker sessions compact with the core's tiers, as the host's own sessions do: a model whose window leaves more than 300,000 tokens compacts at 300,000 through the host compactor, and past 500,000 through Pi's own summary, whose model calls go through the broker like any other.
+A compaction that left the context within 50,000 tokens of its threshold moves the next one to the hard ceiling, so it does not repeat on the next request.
+
+The host compactor runs on the host, where the worker cannot reach (a remote compaction service, say):
+
+```ts
+new PiSandboxRuntime({
+  // ...
+  compaction: {
+    engine: "my-compaction", // recorded as details.engine of its compactions
+    compact: async (request, { channel, signal }) => {
+      // request: PiCompactRequest; return a PiCompaction, or undefined for Pi's summary
+    },
+    timeoutMs: 120_000, // optional; default the smaller of 120 s and a third of turnTimeoutMs
+    maxRequestBytes: 32 * 1024 * 1024, // optional; default 32 MiB
+  },
+});
+```
+
+`PiCompactRequest` carries Pi's preparation: `reason`, `tokensBefore`, `firstKeptEntryId`, `isSplitTurn`, `messagesToSummarize`, `turnPrefixMessages`, `keptMessages` (the messages from `firstKeptEntryId` on), `previousSummary?`, `customInstructions?`, `readFiles` and `modifiedFiles`.
+A `PiCompaction` is Pi's `CompactionResult`: `summary`, `firstKeptEntryId` (the request's), `tokensBefore`, `estimatedTokensAfter?` and `details?` (an object; the broker sets its `engine`).
+A compactor that returns `undefined`, throws, answers out of shape, outlasts `timeoutMs` (its `signal` aborts), or gets a request over `maxRequestBytes` falls back to Pi's summary, and the host logs the reason.
+The timeout may be at most half of `turnTimeoutMs`, so Pi's summary keeps time to run.
+A turn may ask the host for three compactions and send sixteen compaction reports; later compactions fall back to Pi's summary, and while a compactor that ignored its signal still runs, a new request falls back too.
+Without `compaction` the worker registers no compaction handler; the tiers and Pi's summary still apply.
+Compactions are written to the session file in the channel workspace, so they survive container removal and restarts.
+
+The host logs, per channel: `conversation compacted` (`trigger`, `engine` `extension` or `pi`, `tokensBefore`, `tokensAfter`, `nextCompactionAt`), `compaction failed`, `compaction skips the extension for Pi's summary` past the ceiling, and `compaction falls back to Pi's summary` with its `fallback` reason.
+
 ### Worker content and files
 
 The trusted image exports `workerContent(profile): PiWorkerContent` from `/app/worker/content.ts`.
@@ -268,7 +300,10 @@ Never include real auth files or host source in those content directories.
 ### Pi isolation and continuity
 
 Pi containers remain network-none, non-root, read-only-root, capability-free and `no-new-privileges`.
-They have 1.5 GiB RAM with no additional swap, one CPU, 256 PIDs, a 512 MiB temporary filesystem, and bounded Docker logs (two 10 MiB local log files).
+They have 1.5 GiB RAM with no additional swap, one CPU, 256 PIDs, and a 512 MiB temporary filesystem.
+Their logs go to journald tagged `sandbox/<channel>`, so they outlive the container; the Docker daemon must then run under systemd with journald, or containers fail to start.
+journald bounds the lines through its own rate limit and `SystemMaxUse`, not per container; `PiDockerContainerDriver`'s third argument, `{ log: { driver, options } }` (or a function of the channel), names another Docker log driver.
+The worker logs model errors, broker call failures, tool failures and compactions to stdout as JSON lines.
 Only the channel workspace (writable) and host-created broker directory (read-only) are mounted.
 Worker-initiated `/worker/ready`, `/worker/next` and `/worker/result` requests transport turns and byte-backed replies; the host never connects to a guest-created socket or reads guest reply paths.
 Only one idle long poll, one admitted turn and one incoming reply packet per channel are allowed.

package/package.json

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

package/src/index.ts

@@ -38,13 +38,18 @@ export {
 	type PiAttachmentOptions,
 } from "./pi-attachments.ts";
 export {
+	PI_COMPACT_LIMITS,
 	type PiBrokerOptions,
+	type PiCompactor,
 	type PiHostContext,
 	type PiMcpServer,
 	PiSandboxBroker,
 } from "./pi-broker.ts";
 export {
+	defaultContainerLog,
+	demuxDockerLog,
 	type PiContainerDriver,
+	type PiContainerLog,
 	type PiContainerSpec,
 	type PiContainerStatus,
 	PiDockerContainerDriver,
@@ -60,6 +65,11 @@ export {
 	PI_RUN_DIR,
 	PI_THINKING_LEVELS,
 	PI_WORKSPACE,
+	type PiCompaction,
+	type PiCompactionReport,
+	type PiCompactMessage,
+	type PiCompactRequest,
+	type PiCompactResponse,
 	type PiMcpDiscovery,
 	type PiReplyFile,
 	type PiThinkingLevel,
@@ -67,7 +77,10 @@ export {
 	type PiTurnContext,
 	type PiTurnRequest,
 	type PiTurnResponse,
+	type PiWorkerConfig,
 	safeFileName,
+	validateCompactionReport,
+	validateCompactRequest,
 	validateImages,
 	validateReplyFiles,
 } from "./pi-protocol.ts";

package/src/pi-broker.ts

@@ -1,12 +1,20 @@
-import type { ChannelKey } from "pi-roundtable";
+import type { ChannelKey, Logger } from "pi-roundtable";
+import { HARD_COMPACT_TOKENS, scrubDiagnostic } from "pi-roundtable/kit";
 import { type BrokerListener, listenBroker } from "./broker.ts";
 import { piModelInput } from "./pi-model-input.ts";
 import {
 	PI_MEDIA_LIMITS,
+	type PiCompaction,
+	type PiCompactionReport,
+	type PiCompactRequest,
+	type PiCompactResponse,
 	type PiThinkingLevel,
 	type PiToolResponse,
 	type PiTurnRequest,
 	type PiTurnResponse,
+	type PiWorkerConfig,
+	validateCompactionReport,
+	validateCompactRequest,
 	validateImages,
 	validateReplyFiles,
 } from "./pi-protocol.ts";
@@ -25,6 +33,31 @@ export interface PiMcpServer {
 	url: string;
 	tools: readonly string[];
 }
+/** Defaults for a host compactor's limits. */
+export const PI_COMPACT_LIMITS = {
+	/** A larger compact request falls back to Pi's summary unread. */
+	requestBytes: 32 * 1024 * 1024,
+	/** A compactor still running after this falls back to Pi's summary. */
+	timeoutMs: 120_000,
+	/** Compact requests one turn may make; the rest fall back to Pi's summary. */
+	compactsPerTurn: 3,
+	/** Compaction reports one turn may send. */
+	reportsPerTurn: 16,
+} as const;
+/** Compacts a sandbox session on the host, with what the worker cannot reach (a remote service, say). */
+export interface PiCompactor {
+	/** The `engine` this compactor's compactions record in their details; the broker stamps it. */
+	engine: string;
+	/** A compaction, or undefined to leave it to Pi's own summary. A throw also falls back. */
+	compact(
+		request: PiCompactRequest,
+		context: { channel: ChannelKey; signal: AbortSignal },
+	): Promise<PiCompaction | undefined>;
+	/** Longest a compaction may take before Pi's summary runs instead (default 120 seconds). */
+	timeoutMs?: number;
+	/** Largest request accepted, in bytes (default 32 MiB); a larger one falls back to Pi's summary. */
+	maxRequestBytes?: number;
+}
 export interface PiBrokerOptions {
 	model: string;
 	/** Host-only, read at each call. Never sent to the worker. */
@@ -47,6 +80,10 @@ export interface PiBrokerOptions {
 	maxOutputTokens?: number;
 	/** Trusted endpoints can use HTTP only for explicitly configured local MCP. */
 	allowHttpMcp?: boolean;
+	/** Host-side compaction; without it the worker compacts with Pi's summary alone. */
+	compaction?: PiCompactor;
+	/** Receives upstream failures and the worker's compactions, per channel. */
+	logger?: Logger;
 }
 const MODEL_PATHS = new Set([
 	"/anthropic/v1/messages",
@@ -69,6 +106,14 @@ function passthroughHeader(name: string): boolean {
 		RESPONSE_HEADERS.includes(name)
 	);
 }
+/** An error's name, message and cause chain, for a log line. */
+export function errorText(error: unknown): string {
+	if (!(error instanceof Error)) return String(error);
+	const text = `${error.name}: ${error.message}`;
+	return error.cause === undefined
+		? text
+		: `${text} (cause: ${errorText(error.cause)})`;
+}
 function endpoint(raw: string, allowHttp = false): URL {
 	// pi-lens-ignore: unchecked-throwing-call -- invalid trusted endpoint configuration must fail startup.
 	const url = new URL(raw);
@@ -87,6 +132,7 @@ function streamBounded(
 	signal: AbortSignal,
 	maxBytes: number,
 	secret: string,
+	onFailure: (error: unknown) => void,
 ): ReadableStream<Uint8Array> {
 	const reader = response.body?.getReader();
 	let total = 0;
@@ -119,7 +165,8 @@ function streamBounded(
 				const cut = Math.max(0, data.length - tail);
 				if (cut) controller.enqueue(data.subarray(0, cut));
 				carry = data.subarray(cut);
-			} catch {
+			} catch (error) {
+				onFailure(error);
 				await reader?.cancel().catch(() => {});
 				controller.error(new Error("Broker response failed"));
 			}
@@ -128,6 +175,57 @@ function streamBounded(
 	});
 }
 
+/** At most `limit` bytes of a body as text; the rest is cancelled, never read. */
+async function bodyHead(
+	body: ReadableStream<Uint8Array>,
+	limit: number,
+): Promise<string> {
+	const reader = body.getReader();
+	const chunks: Uint8Array[] = [];
+	let size = 0;
+	try {
+		while (size < limit) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			chunks.push(value);
+			size += value.byteLength;
+		}
+	} catch {
+		// The worker's branch reports a broken stream; the log keeps what arrived.
+	} finally {
+		await reader.cancel().catch(() => {});
+	}
+	return Buffer.concat(chunks).subarray(0, limit).toString("utf8");
+}
+/** A credential as it may appear in text: raw, URL-encoded, base64 and hex. */
+function secretForms(secret: string): string[] {
+	if (!secret) return [];
+	return [
+		secret,
+		encodeURIComponent(secret),
+		Buffer.from(secret).toString("base64"),
+		Buffer.from(secret).toString("base64url"),
+		Buffer.from(secret).toString("hex"),
+	];
+}
+/** A compactor's answer, or a rejection once the signal aborts, even if the compactor ignores it. */
+function abortableCompact<T>(
+	promise: Promise<T>,
+	signal: AbortSignal,
+): Promise<T> {
+	return new Promise((resolve, reject) => {
+		const abort = () => reject(signal.reason);
+		if (signal.aborted) {
+			abort();
+			return;
+		}
+		signal.addEventListener("abort", abort, { once: true });
+		promise
+			.then(resolve, reject)
+			.finally(() => signal.removeEventListener("abort", abort));
+	});
+}
+
 /** Explicit subscription mode. A broker is idle except while the host binds one admitted turn. */
 export class PiSandboxBroker {
 	readonly #options: PiBrokerOptions;
@@ -181,6 +279,12 @@ export class PiSandboxBroker {
 			this.#rearmStartup();
 			return new Response("Ready");
 		}
+		if (path === "/worker/config" && request.method === "GET") {
+			const compaction = this.#options.compaction;
+			return Response.json({
+				...(compaction ? { compaction: { engine: compaction.engine } } : {}),
+			} satisfies PiWorkerConfig);
+		}
 		if (path === "/worker/next" && request.method === "GET") {
 			if (this.#next) return new Response("Already waiting", { status: 429 });
 			if (this.#pending && !this.#pending.delivered) {
@@ -306,6 +410,23 @@ export class PiSandboxBroker {
 			(options.maxCalls ?? 128) > 1000
 		)
 			throw new Error("Invalid broker budget");
+		const compaction = options.compaction;
+		if (
+			compaction &&
+			(!/^[a-zA-Z0-9@/._-]{1,100}$/.test(compaction.engine) ||
+				!Number.isSafeInteger(
+					compaction.timeoutMs ?? PI_COMPACT_LIMITS.timeoutMs,
+				) ||
+				(compaction.timeoutMs ?? PI_COMPACT_LIMITS.timeoutMs) < 1000 ||
+				(compaction.timeoutMs ?? PI_COMPACT_LIMITS.timeoutMs) > 600_000 ||
+				!Number.isSafeInteger(
+					compaction.maxRequestBytes ?? PI_COMPACT_LIMITS.requestBytes,
+				) ||
+				(compaction.maxRequestBytes ?? PI_COMPACT_LIMITS.requestBytes) < 1 ||
+				(compaction.maxRequestBytes ?? PI_COMPACT_LIMITS.requestBytes) >
+					96 * 1024 * 1024)
+		)
+			throw new Error("Invalid compactor");
 		if (
 			!Number.isSafeInteger(options.maxOutputTokens ?? 128_000) ||
 			(options.maxOutputTokens ?? 128_000) < 1025 ||
@@ -354,6 +475,12 @@ export class PiSandboxBroker {
 				})),
 			});
 		}
+		if (
+			(url.pathname === "/compaction/compact" ||
+				url.pathname === "/compaction/report") &&
+			!url.search
+		)
+			return this.#compaction(request, url.pathname);
 		const startup = !this.#turn;
 		const turn = this.#turn ?? this.#startup;
 		if (!turn || turn.context.signal.aborted)
@@ -378,6 +505,11 @@ export class PiSandboxBroker {
 		turn.active++;
 		// The turn signal carries the deadline: a long generation or image call must not be cut shorter.
 		const signal = AbortSignal.any([turn.context.signal, request.signal]);
+		const failed = this.#failureLog(
+			turn.context.channel,
+			toolName ? `tool:${toolName}` : server ? `mcp:${server.name}` : "model",
+		);
+		let secret = "";
 		try {
 			const input: unknown = JSON.parse(
 				await boundedText(request.body, 96 * 1024 * 1024),
@@ -405,7 +537,6 @@ export class PiSandboxBroker {
 				return Response.json(result);
 			}
 			let target: string;
-			let secret: string;
 			let body: Record<string, unknown>;
 			const headers = new Headers({
 				"content-type": "application/json",
@@ -478,23 +609,239 @@ export class PiSandboxBroker {
 				if (id && !id.includes(secret) && id.length <= 256)
 					outgoing.set("mcp-session-id", id);
 			}
-			if (upstream.status < 200 || upstream.status > 599)
+			if (upstream.status < 200 || upstream.status > 599) {
+				failed(secret, { status: upstream.status });
 				return new Response("Upstream refused", { status: 502 });
+			}
+			let answer = upstream;
+			if (upstream.status >= 400 && upstream.body) {
+				// The log reads the error body's head from one branch; the worker gets all of it from the other.
+				const [logged, sent] = upstream.body.tee();
+				void bodyHead(logged, 64 * 1024).then((body) =>
+					failed(secret, { status: upstream.status, body }),
+				);
+				answer = new Response(sent, { status: upstream.status });
+			} else if (upstream.status >= 400)
+				failed(secret, { status: upstream.status });
 			return new Response(
 				upstream.status === 204 || upstream.status === 205
 					? null
 					: streamBounded(
-							upstream,
+							answer,
 							signal,
 							PI_MEDIA_LIMITS.totalFileBytes,
 							secret,
+							(error) => failed(secret, { status: upstream.status, error }),
 						),
 				{ headers: outgoing, status: upstream.status },
 			);
-		} catch {
+		} catch (error) {
+			failed(secret, { error });
 			return new Response("Broker call failed", { status: 502 });
 		} finally {
 			turn.active--;
 		}
 	}
+	/** Logs a failed upstream call with its latency; the body and error lose any credential. */
+	#failureLog(channel: ChannelKey, upstream: string) {
+		const started = Date.now();
+		return (
+			secret: string,
+			failure: { status?: number; body?: string; error?: unknown },
+		): void => {
+			const clean = (text: string) =>
+				scrubDiagnostic(
+					secretForms(secret).reduce(
+						(masked, form) => masked.replaceAll(form, "[redacted]"),
+						text,
+					),
+					2000,
+				);
+			this.#options.logger?.warn(
+				{
+					channel,
+					upstream,
+					...(failure.status === undefined ? {} : { status: failure.status }),
+					latencyMs: Date.now() - started,
+					...(failure.body === undefined ? {} : { body: clean(failure.body) }),
+					...(failure.error === undefined
+						? {}
+						: { error: clean(errorText(failure.error)) }),
+				},
+				"sandbox upstream call failed",
+			);
+		};
+	}
+	/** Settles when the running compactor really ends, even after its request fell back. */
+	#compacting: Promise<unknown> | undefined;
+	readonly #compactionUse = new WeakMap<
+		object,
+		{ compacts: number; reports: number }
+	>();
+	/** The worker's compactions, only inside an admitted turn: a host compaction, or a report to log. */
+	async #compaction(request: Request, path: string): Promise<Response> {
+		const turn = this.#turn;
+		if (request.method !== "POST")
+			return new Response("Not found", { status: 404 });
+		if (!turn || turn.context.signal.aborted)
+			return new Response("Turn ended", { status: 410 });
+		const { channel } = turn.context;
+		const logger = this.#options.logger;
+		const use = this.#compactionUse.get(turn) ?? { compacts: 0, reports: 0 };
+		this.#compactionUse.set(turn, use);
+		if (path === "/compaction/report") {
+			// A turn compacts a few times at most; more reports only fill the host's log.
+			if (++use.reports > PI_COMPACT_LIMITS.reportsPerTurn)
+				return new Response("Report budget exhausted", { status: 429 });
+			try {
+				const report: unknown = JSON.parse(
+					await boundedText(request.body, 64 * 1024, turn.context.signal),
+				);
+				validateCompactionReport(report);
+				this.#logReport(channel, report);
+				return new Response("Accepted");
+			} catch {
+				return new Response("Invalid report", { status: 400 });
+			}
+		}
+		const compactor = this.#options.compaction;
+		const fallback = (reason: string): Response => {
+			logger?.warn(
+				{ channel, engine: compactor?.engine, fallback: reason },
+				"compaction falls back to Pi's summary",
+			);
+			return Response.json({
+				ok: false,
+				fallback: reason,
+			} satisfies PiCompactResponse);
+		};
+		if (!compactor) return fallback("the host has no compactor");
+		if (this.#compacting) return fallback("a compaction is already running");
+		if (++use.compacts > PI_COMPACT_LIMITS.compactsPerTurn)
+			return fallback(
+				`the turn already asked for ${PI_COMPACT_LIMITS.compactsPerTurn} compactions`,
+			);
+		const maxBytes =
+			compactor.maxRequestBytes ?? PI_COMPACT_LIMITS.requestBytes;
+		if (Number(request.headers.get("content-length") ?? 0) > maxBytes)
+			return fallback(`the request is over ${maxBytes} bytes`);
+		let running: Promise<unknown> = Promise.resolve();
+		this.#compacting = running;
+		const timeout = AbortSignal.timeout(
+			compactor.timeoutMs ?? PI_COMPACT_LIMITS.timeoutMs,
+		);
+		const signal = AbortSignal.any([
+			turn.context.signal,
+			request.signal,
+			timeout,
+		]);
+		const started = Date.now();
+		try {
+			let compactRequest: unknown;
+			try {
+				compactRequest = JSON.parse(
+					await boundedText(request.body, maxBytes, signal),
+				);
+				validateCompactRequest(compactRequest);
+			} catch (error) {
+				if (signal.aborted) throw error;
+				return fallback(
+					error instanceof Error && error.message === "body too large"
+						? `the request is over ${maxBytes} bytes`
+						: "the request is invalid",
+				);
+			}
+			const compacting = compactor.compact(compactRequest, { channel, signal });
+			running = compacting.catch(() => {});
+			this.#compacting = running;
+			const result = await abortableCompact(compacting, signal);
+			if (!result) return fallback("the compactor declined");
+			const details =
+				result.details === undefined
+					? { engine: compactor.engine }
+					: isRecord(result.details)
+						? { ...result.details, engine: compactor.engine }
+						: undefined;
+			if (
+				!details ||
+				typeof result.summary !== "string" ||
+				result.summary.length === 0 ||
+				result.firstKeptEntryId !== compactRequest.firstKeptEntryId ||
+				!Number.isSafeInteger(result.tokensBefore) ||
+				(result.estimatedTokensAfter !== undefined &&
+					!Number.isSafeInteger(result.estimatedTokensAfter))
+			)
+				return fallback("the compactor's result is invalid");
+			logger?.info(
+				{
+					channel,
+					engine: compactor.engine,
+					tokensBefore: result.tokensBefore,
+					tokensAfter: result.estimatedTokensAfter,
+					latencyMs: Date.now() - started,
+				},
+				"host compactor answered",
+			);
+			return Response.json({
+				ok: true,
+				compaction: {
+					summary: result.summary,
+					firstKeptEntryId: result.firstKeptEntryId,
+					tokensBefore: result.tokensBefore,
+					...(result.estimatedTokensAfter === undefined
+						? {}
+						: { estimatedTokensAfter: result.estimatedTokensAfter }),
+					details,
+				},
+			} satisfies PiCompactResponse);
+		} catch (error) {
+			return fallback(
+				timeout.aborted
+					? `the compactor took over ${compactor.timeoutMs ?? PI_COMPACT_LIMITS.timeoutMs} ms`
+					: signal.aborted
+						? "the compaction was aborted"
+						: `the compactor failed: ${scrubDiagnostic(errorText(error), 2000)}`,
+			);
+		} finally {
+			// A compactor that ignored its signal still holds the slot until it really ends.
+			void running.then(() => {
+				if (this.#compacting === running) this.#compacting = undefined;
+			});
+		}
+	}
+	/** Logs a worker compaction the way the host logs its own sessions' compactions. */
+	#logReport(channel: ChannelKey, report: PiCompactionReport): void {
+		const logger = this.#options.logger;
+		if (report.type === "bypass") {
+			logger?.info(
+				{
+					channel,
+					reason: report.reason,
+					tokensBefore: report.tokensBefore,
+					ceiling: HARD_COMPACT_TOKENS,
+				},
+				"compaction skips the extension for Pi's summary",
+			);
+			return;
+		}
+		const trigger = report.reason === "manual" ? "self" : report.reason;
+		if (!report.engine) {
+			logger?.warn(
+				{ channel, trigger, aborted: report.aborted, error: report.error },
+				"compaction failed",
+			);
+			return;
+		}
+		logger?.info(
+			{
+				channel,
+				trigger,
+				engine: report.engine,
+				tokensBefore: report.tokensBefore,
+				tokensAfter: report.tokensAfter,
+				nextCompactionAt: report.nextCompactionAt,
+			},
+			"conversation compacted",
+		);
+	}
 }