@gajae-code/agent-core 0.11.0 → 0.11.2

package/src/agent.ts

@@ -308,6 +308,11 @@ interface CursorToolResultEntry {
 	textLengthAtCall: number;
 }
 
+export type AgentQueueSnapshot = {
+	steering: AgentMessage[];
+	followUp: AgentMessage[];
+};
+
 export class Agent {
 	#state: AgentState = {
 		systemPrompt: [],
@@ -1009,6 +1014,20 @@ export class Agent {
 		this.#followUpQueue = [...messages, ...this.#followUpQueue];
 	}
 
+	/** Snapshot both executable queues as one atomic session-level view. */
+	snapshotQueues(): AgentQueueSnapshot {
+		return {
+			steering: this.#steeringQueue.slice(),
+			followUp: this.#followUpQueue.slice(),
+		};
+	}
+
+	/** Replace both executable queues with a prior snapshot. */
+	restoreQueues(snapshot: AgentQueueSnapshot): void {
+		this.#steeringQueue = snapshot.steering.slice();
+		this.#followUpQueue = snapshot.followUp.slice();
+	}
+
 	#dequeueSteeringMessages(): AgentMessage[] {
 		if (this.#steeringMode === "one-at-a-time") {
 			if (this.#steeringQueue.length > 0) {
@@ -1607,7 +1626,7 @@ export class Agent {
 					this.requestRunTerminal(managedLogicalRunOwner ?? runId, managedDecision.terminal);
 				} else if (managedOutcome.type === "run_terminal") {
 					this.requestRunTerminal(managedLogicalRunOwner ?? runId, { stopReason: managedOutcome.reason });
-				} else if (managedDecision?.type !== "retry") {
+				} else if (managedDecision?.type !== "retry" && managedDecision?.type !== "maintenance") {
 					this.#finalizeRun(managedLogicalRunOwner ?? runId);
 				}
 			}
@@ -1660,7 +1679,10 @@ export class Agent {
 			});
 		} finally {
 			let continuation: ManagedAttemptContinuation | undefined;
-			if (managedOutcome?.type === "retryable_discarded" && managedDecision?.type === "retry") {
+			if (
+				managedOutcome?.type !== "run_terminal" &&
+				(managedDecision?.type === "retry" || managedDecision?.type === "maintenance")
+			) {
 				continuation = managedDecision.continuation;
 			}
 			const ownership: ManagedAttemptContinuationOwnership = {
@@ -1691,7 +1713,18 @@ export class Agent {
 			if (continuation && ownership.isCurrent()) {
 				try {
 					await continuation(ownership);
-					if (this.#activeRunId === undefined && this.#managedLogicalRunOwner === managedLogicalRunOwner) {
+					if (
+						managedDecision?.type === "maintenance" &&
+						this.#terminalizedLogicalRunIds.has(managedLogicalRunOwner ?? runId) &&
+						this.#managedLogicalRunOwner === managedLogicalRunOwner
+					) {
+						this.#managedLogicalRunOwner = undefined;
+					}
+					if (
+						managedDecision?.type !== "maintenance" &&
+						this.#activeRunId === undefined &&
+						this.#managedLogicalRunOwner === managedLogicalRunOwner
+					) {
 						this.#managedLogicalRunOwner = undefined;
 					}
 				} catch (err) {

package/src/compaction/compaction.ts

@@ -29,7 +29,6 @@ import {
 	withOpenAiRemoteCompactionPreserveData,
 } from "./openai";
 import autoHandoffThresholdFocusPrompt from "./prompts/auto-handoff-threshold-focus.md" with { type: "text" };
-import compactionShortSummaryPrompt from "./prompts/compaction-short-summary.md" with { type: "text" };
 import compactionSummaryPrompt from "./prompts/compaction-summary.md" with { type: "text" };
 import compactionTurnPrefixPrompt from "./prompts/compaction-turn-prefix.md" with { type: "text" };
 import compactionUpdateSummaryPrompt from "./prompts/compaction-update-summary.md" with { type: "text" };
@@ -144,6 +143,18 @@ export interface CompactionSettings {
 	remoteEndpoint?: string;
 }
 
+export type RemoteCompactionFallbackHealthEvent =
+	| { kind: "success"; model: string; provider: string }
+	| { kind: "fallback"; model: string; provider: string; error: string };
+
+export interface RemoteCompactionFallbackHealthHooks {
+	recordRemoteCompactionFallback(event: RemoteCompactionFallbackHealthEvent): void;
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}
+
 export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
 	enabled: true,
 	strategy: "context-full",
@@ -498,7 +509,8 @@ function collectMessageFragments(message: AgentMessage): { fragments: string[];
 	}
 
 	switch (message.role) {
-		case "user": {
+		case "user":
+		case "custom": {
 			const content = (message as { content: string | Array<{ type: string; text?: string }> }).content;
 			if (typeof content === "string") {
 				fragments.push(content);
@@ -698,8 +710,6 @@ export function findCutPoint(
 
 	for (let i = endIndex - 1; i >= startIndex; i--) {
 		const entry = entries[i];
-		if (entry.type !== "message") continue;
-
 		// Estimate this message's size
 		const messageTokens = estimateEntryTokens(entry);
 		accumulatedTokens += messageTokens;
@@ -757,8 +767,6 @@ const SUMMARIZATION_PROMPT = prompt.render(compactionSummaryPrompt);
 
 const UPDATE_SUMMARIZATION_PROMPT = prompt.render(compactionUpdateSummaryPrompt);
 
-const SHORT_SUMMARY_PROMPT = prompt.render(compactionShortSummaryPrompt);
-
 const HANDOFF_DOCUMENT_PROMPT = prompt.render(handoffDocumentPrompt);
 
 export const AUTO_HANDOFF_THRESHOLD_FOCUS = prompt.render(autoHandoffThresholdFocusPrompt);
@@ -784,8 +792,7 @@ export interface SummaryOptions {
 	/**
 	 * Optional telemetry handle. When provided, every LLM call emitted during
 	 * compaction is wrapped in an OTEL chat span tagged with
-	 * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
-	 * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+	 * `pi.gen_ai.oneshot.kind` (`compaction_summary` or `compaction_turn_prefix`).
 	 */
 	telemetry?: AgentTelemetry;
 	authCredentialType?: "api_key" | "oauth";
@@ -799,6 +806,8 @@ export interface SummaryOptions {
 	providerSessionState?: Map<string, ProviderSessionState>;
 	/** Hint that websocket transport should be preferred when supported by the provider implementation. */
 	preferWebsockets?: boolean;
+	/** Session-owned health sink for remote-compaction fallback transition logging. */
+	remoteCompactionFallbackHealth?: RemoteCompactionFallbackHealthHooks;
 }
 
 /**
@@ -1040,66 +1049,11 @@ export async function generateHandoff(
 		.join("\n");
 }
 
-async function generateShortSummary(
-	recentMessages: AgentMessage[],
-	historySummary: string | undefined,
-	model: Model,
-	reserveTokens: number,
-	apiKey: string,
-	signal?: AbortSignal,
-	options?: SummaryOptions,
-): Promise<string> {
-	const maxTokens = Math.min(512, Math.floor(0.2 * reserveTokens));
-	const llmMessages = (options?.convertToLlm ?? convertToLlm)(recentMessages);
-	const conversationText = boundConversationTextForSummary(serializeConversation(llmMessages), model, maxTokens);
-
-	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
-	if (historySummary) {
-		promptText += `<previous-summary>\n${historySummary}\n</previous-summary>\n\n`;
-	}
-	promptText += formatAdditionalContext(options?.extraContext);
-	promptText += SHORT_SUMMARY_PROMPT;
-
-	if (options?.remoteEndpoint) {
-		const remote = await requestRemoteCompaction(
-			options.remoteEndpoint,
-			{
-				systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
-				prompt: promptText,
-			},
-			signal,
-		);
-		return remote.summary;
-	}
-
-	const response = await instrumentedCompleteSimple(
-		model,
-		{
-			systemPrompt: [SUMMARIZATION_SYSTEM_PROMPT],
-			messages: [{ role: "user", content: [{ type: "text", text: promptText }], timestamp: Date.now() }],
-		},
-		{
-			maxTokens,
-			signal,
-			apiKey,
-			reasoning: Effort.High,
-			initiatorOverride: options?.initiatorOverride,
-			metadata: options?.metadata,
-			sessionId: options?.sessionId,
-			providerSessionState: options?.providerSessionState,
-			preferWebsockets: options?.preferWebsockets,
-		},
-		{ telemetry: options?.telemetry, oneshotKind: "compaction_short_summary" },
-	);
-
-	if (response.stopReason === "error") {
-		throw new Error(`Short summary failed: ${response.errorMessage || "Unknown error"}`);
-	}
-
-	return response.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map(c => c.text)
-		.join("\n");
+/** Derive a display summary locally to avoid a second compaction LLM request. */
+function deriveShortSummary(summary: string): string {
+	const firstParagraph = summary.trim().split(/\n\s*\n/, 1)[0] ?? "";
+	const maxLength = 2_000;
+	return firstParagraph.length <= maxLength ? firstParagraph : `${firstParagraph.slice(0, maxLength - 1)}…`;
 }
 
 // ============================================================================
@@ -1149,6 +1103,11 @@ export interface PrepareCompactionOptions {
 	 * (the confounded raw promptTokens/estimatedTokens quotient is never used).
 	 */
 	tokenCorrectionRatio?: number;
+	/**
+	 * Model context-window size. Windows below 66k retain the legacy fixed
+	 * keepRecentTokens behavior; larger windows scale the keep window to 30%.
+	 */
+	contextWindow?: number;
 }
 
 export function prepareCompaction(
@@ -1179,13 +1138,42 @@ export function prepareCompaction(
 	// counts system+tools+full history while estimatedTokens counted only the
 	// post-boundary slice, so it was confounded and only ever shrank the window.
 	// Here the correction is bidirectional and clamped to [0.5, 2].
-	const keepRecentTokens = settings.keepRecentTokens;
+	const configuredKeepRecentTokens = settings.keepRecentTokens;
+	const contextWindow = options.contextWindow;
+	const thresholdSafeKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow > 1
+			? Math.max(
+					1,
+					resolveThresholdTokens(contextWindow, settings) - effectiveReserveTokens(contextWindow, settings, 0),
+				)
+			: configuredKeepRecentTokens;
+	const keepRecentTokens = Math.min(configuredKeepRecentTokens, thresholdSafeKeepRecentTokens);
+	// Preserve the legacy fixed window for smaller models. At 66k and above,
+	// retain up to 30% of the model context, but never enough to leave the
+	// post-compaction prompt immediately above its configured threshold.
+	const scaledKeepRecentTokens =
+		contextWindow !== undefined && Number.isFinite(contextWindow) && contextWindow >= 66_000
+			? Math.min(thresholdSafeKeepRecentTokens, Math.max(keepRecentTokens, Math.floor(contextWindow * 0.3)))
+			: keepRecentTokens;
 	const rawRatio = options.tokenCorrectionRatio;
 	const appliedRatio =
 		rawRatio !== undefined && Number.isFinite(rawRatio) && rawRatio > 0
 			? Math.min(TOKEN_CORRECTION_MAX_RATIO, Math.max(TOKEN_CORRECTION_MIN_RATIO, rawRatio))
 			: 1;
-	const keepRecentTokensCorrected = Math.max(1, Math.round(keepRecentTokens / appliedRatio));
+	// Preserve an explicit keep floor that already covers the whole history: manual
+	// and emergency callers rely on prepareCompaction returning undefined rather
+	// than manufacturing a summary with no useful reduction. Otherwise, a scaled
+	// window that exceeds a short history falls back to the threshold-safe floor.
+	const historyTokens = pathEntries
+		.slice(boundaryStart, boundaryEnd)
+		.reduce((tokens, entry) => tokens + estimateEntryTokens(entry), 0);
+	const effectiveKeepRecentTokens =
+		configuredKeepRecentTokens > historyTokens
+			? configuredKeepRecentTokens
+			: scaledKeepRecentTokens > keepRecentTokens && scaledKeepRecentTokens > historyTokens
+				? keepRecentTokens
+				: scaledKeepRecentTokens;
+	const keepRecentTokensCorrected = Math.max(1, Math.round(effectiveKeepRecentTokens / appliedRatio));
 
 	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokensCorrected);
 
@@ -1305,6 +1293,7 @@ export async function compact(
 		sessionId: options?.sessionId,
 		providerSessionState: options?.providerSessionState,
 		preferWebsockets: options?.preferWebsockets,
+		remoteCompactionFallbackHealth: options?.remoteCompactionFallbackHealth,
 	};
 
 	let preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, undefined);
@@ -1331,12 +1320,28 @@ export async function compact(
 					{ authCredentialType: options?.authCredentialType },
 				);
 				preserveData = withOpenAiRemoteCompactionPreserveData(previousPreserveData, remote);
-			} catch (err) {
-				logger.warn("OpenAI remote compaction failed, falling back to local summarization", {
-					error: err instanceof Error ? err.message : String(err),
+				summaryOptions.remoteCompactionFallbackHealth?.recordRemoteCompactionFallback({
+					kind: "success",
 					model: model.id,
 					provider: model.provider,
 				});
+			} catch (err) {
+				if (signal?.aborted || isAbortError(err)) throw err;
+				const error = err instanceof Error ? err.message : String(err);
+				if (summaryOptions.remoteCompactionFallbackHealth) {
+					summaryOptions.remoteCompactionFallbackHealth.recordRemoteCompactionFallback({
+						kind: "fallback",
+						error,
+						model: model.id,
+						provider: model.provider,
+					});
+				} else {
+					logger.warn("OpenAI remote compaction failed, falling back to local summarization", {
+						error,
+						model: model.id,
+						provider: model.provider,
+					});
+				}
 			}
 		}
 	}
@@ -1406,28 +1411,10 @@ export async function compact(
 		summary = "No prior history.";
 	}
 
-	const shortSummary = await generateShortSummary(
-		recentMessages,
-		summary,
-		model,
-		settings.reserveTokens,
-		apiKey,
-		signal,
-		{
-			extraContext: options?.extraContext,
-			remoteEndpoint: summaryOptions.remoteEndpoint,
-			initiatorOverride: summaryOptions.initiatorOverride,
-			metadata: summaryOptions.metadata,
-			telemetry: summaryOptions.telemetry,
-			sessionId: summaryOptions.sessionId,
-			providerSessionState: summaryOptions.providerSessionState,
-			preferWebsockets: summaryOptions.preferWebsockets,
-		},
-	);
-
 	// Compute file lists and append to summary
 	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
 	summary = upsertFileOperations(summary, readFiles, modifiedFiles);
+	const shortSummary = deriveShortSummary(summary);
 
 	if (!firstKeptEntryId) {
 		throw new Error("First kept entry has no ID - session may need migration");

package/src/compaction/openai.ts

@@ -514,18 +514,14 @@ export async function requestOpenAiRemoteCompaction(
 	});
 
 	if (!response.ok) {
-		const errorText = await response.text().catch(() => "");
-		logger.warn("OpenAI remote compaction failed", {
-			endpoint,
-			status: response.status,
-			statusText: response.statusText,
-			errorText,
-		});
 		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
 	}
 
-	const data = (await response.json()) as { output?: unknown[] } | undefined;
-	const rawOutput = data?.output ?? [];
+	const data = (await response.json()) as { output?: unknown } | undefined;
+	if (!Array.isArray(data?.output)) {
+		throw new Error(`Remote compaction response malformed output (outputType=${typeof data?.output})`);
+	}
+	const rawOutput = data.output;
 	const replacementHistory = rawOutput.filter(
 		(item): item is Record<string, unknown> =>
 			!!item && typeof item === "object" && shouldKeepOpenAiCompactOutputItem(item as Record<string, unknown>),
@@ -539,15 +535,9 @@ export async function requestOpenAiRemoteCompaction(
 		const outputTypes = rawOutput.map(item =>
 			typeof item === "object" && item !== null ? (item as Record<string, unknown>).type : typeof item,
 		);
-		logger.warn("Remote compaction response missing compaction item", {
-			endpoint,
-			model: model.id,
-			provider: model.provider,
-			rawOutputLength: rawOutput.length,
-			outputTypes,
-			replacementHistoryLength: replacementHistory.length,
-		});
-		throw new Error("Remote compaction response missing compaction item");
+		throw new Error(
+			`Remote compaction response missing compaction item (rawOutputLength=${rawOutput.length}, outputTypes=${outputTypes.join(",")}, replacementHistoryLength=${replacementHistory.length})`,
+		);
 	}
 	return { provider: model.provider, replacementHistory, compactionItem };
 }
@@ -572,13 +562,6 @@ export async function requestRemoteCompaction(
 	});
 
 	if (!response.ok) {
-		const errorText = await response.text().catch(() => "");
-		logger.warn("Remote compaction failed", {
-			endpoint,
-			status: response.status,
-			statusText: response.statusText,
-			errorText,
-		});
 		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
 	}
 

package/src/compaction/pruning.ts

@@ -267,6 +267,56 @@ function readBasePath(path: string): string {
 	return base;
 }
 
+type ReadLineRange = { start: number; end: number };
+
+const DEFAULT_READ_LINE_LIMIT = 500;
+
+/** Parse trailing read selectors using the read tool's actual bounded default. */
+function readLineRanges(path: string): ReadLineRange[] {
+	let target = path;
+	let raw = false;
+	while (/:(?:raw|conflicts)$/.test(target)) {
+		raw ||= target.endsWith(":raw");
+		target = target.replace(/:(?:raw|conflicts)$/, "");
+	}
+	const match = target.match(/:(\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)$/);
+	if (!match) return raw ? [{ start: 1, end: Number.POSITIVE_INFINITY }] : [];
+	return match[1].split(",").flatMap(part => {
+		const range = part.match(/^(\d+)(?:([-+])(\d+))?$/);
+		if (!range) return [];
+		const start = Number(range[1]);
+		const end =
+			range[2] === "+"
+				? start + Number(range[3]) - 1
+				: range[2] === "-"
+					? Number(range[3])
+					: start + DEFAULT_READ_LINE_LIMIT - 1;
+		return start > 0 && end >= start ? [{ start, end }] : [];
+	});
+}
+
+function strictlyContainsReadRange(container: ReadLineRange, contained: ReadLineRange): boolean {
+	return (
+		container.start <= contained.start &&
+		container.end >= contained.end &&
+		(container.start < contained.start || container.end > contained.end)
+	);
+}
+
+function readSupersedesRead(
+	later: ToolCall,
+	earlier: ToolCall,
+	lineRangesByCall: ReadonlyMap<ToolCall, ReadLineRange[]>,
+): boolean {
+	const laterRanges = lineRangesByCall.get(later);
+	const earlierRanges = lineRangesByCall.get(earlier);
+	return (
+		laterRanges?.length === 1 &&
+		earlierRanges?.length === 1 &&
+		strictlyContainsReadRange(laterRanges[0], earlierRanges[0])
+	);
+}
+
 /**
  * Stable identity for "the same logical lookup": same tool re-targeting the
  * same subject. A later result with the same key supersedes earlier ones.
@@ -275,9 +325,23 @@ function readBasePath(path: string): string {
  * (`skip`) and result-shaping flags (`i`, `gitignore`): a later page or a
  * differently-shaped search complements earlier output, it does not replace it.
  */
+const IDEMPOTENT_BASH_COMMAND =
+	/^(?:(?:bun|npm|pnpm|yarn)\s+(?:run\s+)?(?:test|build)\b|git\s+status\b|cargo\s+build\b|(?:make|just)\s+build\b)/;
+
+function normalizedIdempotentBashCommand(call: ToolCall): string | undefined {
+	if (call.name !== "bash") return undefined;
+	const command = call.arguments.command;
+	if (typeof command !== "string") return undefined;
+	const normalized = command.trim().replace(/\s+/g, " ");
+	if (/[;&|]/.test(normalized) || !IDEMPOTENT_BASH_COMMAND.test(normalized)) return undefined;
+	return JSON.stringify([normalized, typeof call.arguments.cwd === "string" ? call.arguments.cwd : undefined]);
+}
+
 function toolTargetKey(call: ToolCall): string | undefined {
 	const path = toolCallPath(call);
 	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
+	const command = normalizedIdempotentBashCommand(call);
+	if (command !== undefined) return JSON.stringify([call.name, "command", command]);
 	const pattern = call.arguments.pattern;
 	if (typeof pattern === "string" && pattern.length > 0) {
 		const paths = call.arguments.paths;
@@ -372,8 +436,9 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	type ResultMeta = { key?: string; call: ToolCall; message: ToolResultMessage };
 	const lastResultIndexByKey = new Map<string, number>();
-	const resultMeta = new Map<number, { key?: string; call: ToolCall; message: ToolResultMessage }>();
+	const resultMeta = new Map<number, ResultMeta>();
 	const lastEditIndexByPath = new Map<string, number>();
 
 	for (let i = 0; i < entries.length; i++) {
@@ -439,6 +504,31 @@ function buildStalenessIndex(entries: SessionEntry[]): StalenessIndex {
 		}
 	}
 
+	const readsByBasePath = new Map<string, Array<[number, ResultMeta]>>();
+	const lineRangesByCall = new Map<ToolCall, ReadLineRange[]>();
+	for (const [index, meta] of resultMeta) {
+		if (meta.call.name !== "read") continue;
+		const path = toolCallPath(meta.call);
+		if (!path) continue;
+		lineRangesByCall.set(meta.call, readLineRanges(path));
+		const basePath = readBasePath(path);
+		const group = readsByBasePath.get(basePath);
+		if (group) group.push([index, meta]);
+		else readsByBasePath.set(basePath, [[index, meta]]);
+	}
+	for (const reads of readsByBasePath.values()) {
+		if (reads.length < 2) continue;
+		for (let earlier = 0; earlier < reads.length - 1; earlier++) {
+			const [index, meta] = reads[earlier];
+			for (let later = earlier + 1; later < reads.length; later++) {
+				if (readSupersedesRead(reads[later][1].call, meta.call, lineRangesByCall)) {
+					staleResultIndices.add(index);
+					break;
+				}
+			}
+		}
+	}
+
 	return { staleResultIndices };
 }
 export function pruneAssistantToolArguments(
@@ -596,6 +686,13 @@ function collectToolOutputPruneCandidates(
 	return { candidates, tokensSaved };
 }
 
+function minimumSavings(config: PruneConfig, options: PruneToolOutputsOptions = {}): number {
+	const relaxedMinimum = options.relaxedMinimum;
+	return typeof relaxedMinimum === "number" && Number.isFinite(relaxedMinimum)
+		? Math.min(config.minimumSavings, Math.max(0, relaxedMinimum))
+		: config.minimumSavings;
+}
+
 /**
  * Estimate the token savings {@link pruneToolOutputs} would achieve, without
  * mutating any entry. Returns 0 savings when below the configured minimum so the
@@ -604,9 +701,10 @@ function collectToolOutputPruneCandidates(
 export function estimateToolOutputPruneSavings(
 	entries: SessionEntry[],
 	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
 ): { prunableCount: number; tokensSaved: number } {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimumSavings(config, options) || candidates.length === 0) {
 		return { prunableCount: 0, tokensSaved: 0 };
 	}
 	return { prunableCount: candidates.length, tokensSaved };
@@ -630,10 +728,20 @@ export function shouldRunMaintenancePrune(args: {
 	return args.estimatedSavings > args.cacheEpochResetCost;
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+export interface PruneToolOutputsOptions {
+	/** Lower the usual minimum only when the caller is already over its compaction threshold. */
+	relaxedMinimum?: number;
+}
+
+export function pruneToolOutputs(
+	entries: SessionEntry[],
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+	options: PruneToolOutputsOptions = {},
+): PruneResult {
 	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
+	const minimum = minimumSavings(config, options);
 
-	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+	if (tokensSaved < minimum || candidates.length === 0) {
 		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}