@prometheus-ai/agent-core 0.5.4 → 0.5.8

package/src/compaction/openai.ts

@@ -12,20 +12,21 @@
  *   with `{ summary, shortSummary? }`.
  */
 
-import {
-	CODEX_BASE_URL,
-	getCodexAccountId,
-	OPENAI_HEADER_VALUES,
-	OPENAI_HEADERS,
-} from "@prometheus-ai/ai/providers/openai-codex/constants";
+import { ProviderHttpError } from "@prometheus-ai/ai/errors";
 import { parseTextSignature } from "@prometheus-ai/ai/providers/openai-responses-shared";
 import { transformMessages } from "@prometheus-ai/ai/providers/transform-messages";
-import type { AssistantMessage, Message, Model } from "@prometheus-ai/ai/types";
+import type { AssistantMessage, FetchImpl, Message, Model } from "@prometheus-ai/ai/types";
 import {
 	getOpenAIResponsesHistoryItems,
 	getOpenAIResponsesHistoryPayload,
 	normalizeResponsesToolCallId,
 } from "@prometheus-ai/ai/utils";
+import {
+	CODEX_BASE_URL,
+	getCodexAccountId,
+	OPENAI_HEADER_VALUES,
+	OPENAI_HEADERS,
+} from "@prometheus-ai/catalog/wire/codex";
 import { logger } from "@prometheus-ai/utils";
 
 // ============================================================================
@@ -34,6 +35,23 @@ import { logger } from "@prometheus-ai/utils";
 
 export const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
 
+/**
+ * Hard ceiling on remote compaction HTTP requests. Unlike every provider
+ * stream (guarded by first-event/idle watchdogs in pi-ai), these are raw
+ * fetches awaiting one non-streamed JSON body — a connection silently dropped
+ * by a middlebox would otherwise hang the whole compaction pipeline forever
+ * (frozen "Auto context-full maintenance…" spinner, manual /compact queueing
+ * behind it). On timeout the caller falls back to local summarization.
+ */
+export const REMOTE_COMPACTION_TIMEOUT_MS = 180_000;
+
+/** Race the caller's signal against the request timeout; `timeoutMs <= 0` disables the watchdog. */
+function withRequestTimeout(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal | undefined {
+	if (timeoutMs <= 0) return signal;
+	const timeout = AbortSignal.timeout(timeoutMs);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
 export type OpenAiRemoteCompactionItem = {
 	type: "compaction" | "compaction_summary";
 	encrypted_content?: string;
@@ -146,50 +164,14 @@ export function withOpenAiRemoteCompactionPreserveData(
 // Input/output filtering for OpenAI compact endpoint
 // ============================================================================
 
-function estimateOpenAiCompactInputTokens(input: Array<Record<string, unknown>>, instructions: string): number {
-	let chars = instructions.length;
-	for (const item of input) {
-		chars += JSON.stringify(item).length;
-	}
-	return Math.ceil(chars / 4);
-}
-
 function shouldTrimOpenAiCompactInputItem(item: Record<string, unknown>): boolean {
 	return item.type === "function_call_output" || (item.type === "message" && item.role === "developer");
 }
 
-function shouldKeepOpenAiCompactOutputUserMessage(item: Record<string, unknown>): boolean {
-	if (item.role !== "user") return false;
-	const content = item.content;
-	if (!Array.isArray(content) || content.length === 0) return false;
-	const contextualFragmentPatterns = [
-		[/^<system-reminder>[\s\S]*<\/system-reminder>$/i, /<system-reminder>/i],
-		[/^#\s*AGENTS\.md instructions for\b[\s\S]*<\/INSTRUCTIONS>$/i, /# AGENTS.md instructions/],
-		[/^<environment-context>[\s\S]*<\/environment-context>$/i, /<environment-context>/i],
-		[/^<skill>[\s\S]*<\/skill>$/i, /<skill>/i],
-		[/^<user-shell-command>[\s\S]*<\/user-shell-command>$/i, /<user-shell-command>/i],
-		[/^<turn-aborted>[\s\S]*<\/turn-aborted>$/i, /<turn-aborted>/i],
-		[/^<subagent-notification>[\s\S]*<\/subagent-notification>$/i, /<subagent-notification>/i],
-	] as const;
-	return content.every(part => {
-		if (!part || typeof part !== "object") return false;
-		const candidate = part as { type?: unknown; text?: unknown };
-		if (candidate.type === "input_image") return true;
-		if (candidate.type !== "input_text" || typeof candidate.text !== "string") return false;
-		const trimmed = candidate.text.trim();
-		if (trimmed.length === 0) return false;
-		return !contextualFragmentPatterns.some(([strictPattern, markerPattern]) => {
-			return strictPattern.test(trimmed) || markerPattern.test(trimmed);
-		});
-	});
-}
-
 function shouldKeepOpenAiCompactOutputItem(item: Record<string, unknown>): boolean {
 	if (item.type === "compaction" || item.type === "compaction_summary") return true;
 	if (item.type !== "message") return false;
-	if (item.role === "developer") return false;
-	if (item.role === "assistant") return true;
-	return shouldKeepOpenAiCompactOutputUserMessage(item);
+	return item.role === "assistant" || item.role === "user";
 }
 
 function trimOpenAiCompactInput(
@@ -198,16 +180,29 @@ function trimOpenAiCompactInput(
 	instructions: string,
 ): Array<Record<string, unknown>> {
 	const trimmed = [...input];
-	while (trimmed.length > 0 && estimateOpenAiCompactInputTokens(trimmed, instructions) > contextWindow) {
+	// Per-item serialized sizes are cached and decremented on removal.
+	// Re-stringifying the whole input per popped item was O(N²) in total chars
+	// — hundreds of MB of stringify churn on a 200k-token codex history,
+	// blocking the event loop for seconds (same class as the addOpenAiCallIds
+	// fix above).
+	const sizes = trimmed.map(item => JSON.stringify(item).length);
+	let chars = instructions.length;
+	for (const size of sizes) chars += size;
+	const removeAt = (index: number): void => {
+		chars -= sizes[index] ?? 0;
+		trimmed.splice(index, 1);
+		sizes.splice(index, 1);
+	};
+	while (trimmed.length > 0 && Math.ceil(chars / 4) > contextWindow) {
 		const last = trimmed[trimmed.length - 1];
 		if (last?.type === "function_call_output" || last?.type === "custom_tool_call_output") {
 			const callId = typeof last.call_id === "string" ? last.call_id : undefined;
 			const callType = last.type === "custom_tool_call_output" ? "custom_tool_call" : "function_call";
-			trimmed.pop();
+			removeAt(trimmed.length - 1);
 			if (callId) {
 				const matchingCallIndex = trimmed.findLastIndex(item => item.type === callType && item.call_id === callId);
 				if (matchingCallIndex >= 0) {
-					trimmed.splice(matchingCallIndex, 1);
+					removeAt(matchingCallIndex);
 				}
 			}
 			continue;
@@ -215,29 +210,32 @@ function trimOpenAiCompactInput(
 		if (!last || !shouldTrimOpenAiCompactInputItem(last)) {
 			break;
 		}
-		trimmed.pop();
+		removeAt(trimmed.length - 1);
 	}
 	return trimmed;
 }
 
-function collectKnownOpenAiCallIds(items: Array<Record<string, unknown>>): Set<string> {
-	const knownCallIds = new Set<string>();
+// Register every tool-call id in `items` (and the subset using the custom-tool
+// wire shape) into the running sets. The history builder maintains both sets
+// incrementally as native history is appended, so this only scans the
+// newly-added items (or, after a full-snapshot replace, the fresh input) rather
+// than re-scanning the whole growing history per message — the latter was
+// O(N²) and blocked the event loop for seconds while compacting large codex
+// contexts (frozen spinner until the next forced render).
+function addOpenAiCallIds(
+	items: Array<Record<string, unknown>>,
+	knownCallIds: Set<string>,
+	customCallIds: Set<string>,
+): void {
 	for (const item of items) {
-		if ((item.type === "function_call" || item.type === "custom_tool_call") && typeof item.call_id === "string") {
+		if (typeof item.call_id !== "string") continue;
+		if (item.type === "function_call") {
+			knownCallIds.add(item.call_id);
+		} else if (item.type === "custom_tool_call") {
 			knownCallIds.add(item.call_id);
-		}
-	}
-	return knownCallIds;
-}
-
-function collectCustomOpenAiCallIds(items: Array<Record<string, unknown>>): Set<string> {
-	const customCallIds = new Set<string>();
-	for (const item of items) {
-		if (item.type === "custom_tool_call" && typeof item.call_id === "string") {
 			customCallIds.add(item.call_id);
 		}
 	}
-	return customCallIds;
 }
 
 // ============================================================================
@@ -265,16 +263,16 @@ export function buildOpenAiNativeHistory(
 	const transformedMessages = transformMessages(messages, model, id => normalizeOpenAiCompactionToolCallId(id));
 
 	let msgIndex = 0;
-	let knownCallIds = collectKnownOpenAiCallIds(input);
-	let customCallIds = collectCustomOpenAiCallIds(input);
+	const knownCallIds = new Set<string>();
+	const customCallIds = new Set<string>();
+	addOpenAiCallIds(input, knownCallIds, customCallIds);
 	for (const message of transformedMessages) {
 		if (message.role === "user" || message.role === "developer") {
 			const providerPayload = (message as { providerPayload?: AssistantMessage["providerPayload"] }).providerPayload;
 			const historyItems = getOpenAIResponsesHistoryItems(providerPayload, model.provider);
 			if (historyItems) {
 				input.push(...historyItems);
-				knownCallIds = collectKnownOpenAiCallIds(input);
-				customCallIds = collectCustomOpenAiCallIds(input);
+				addOpenAiCallIds(historyItems, knownCallIds, customCallIds);
 				msgIndex++;
 				continue;
 			}
@@ -317,11 +315,13 @@ export function buildOpenAiNativeHistory(
 			if (providerPayload) {
 				if (providerPayload.dt) {
 					input.push(...providerPayload.items);
+					addOpenAiCallIds(providerPayload.items, knownCallIds, customCallIds);
 				} else {
 					input.splice(0, input.length, ...providerPayload.items);
+					knownCallIds.clear();
+					customCallIds.clear();
+					addOpenAiCallIds(input, knownCallIds, customCallIds);
 				}
-				knownCallIds = collectKnownOpenAiCallIds(input);
-				customCallIds = collectCustomOpenAiCallIds(input);
 				msgIndex++;
 				continue;
 			}
@@ -451,11 +451,12 @@ export async function requestOpenAiRemoteCompaction(
 	compactInput: Array<Record<string, unknown>>,
 	instructions: string,
 	signal?: AbortSignal,
+	opts?: { fetch?: FetchImpl; timeoutMs?: number },
 ): Promise<OpenAiRemoteCompactionResponse> {
 	const endpoint = resolveOpenAiCompactEndpoint(model);
 	const request: OpenAiRemoteCompactionRequest = {
 		model: model.id,
-		input: trimOpenAiCompactInput(compactInput, model.contextWindow, instructions),
+		input: trimOpenAiCompactInput(compactInput, model.contextWindow ?? Number.POSITIVE_INFINITY, instructions),
 		instructions,
 	};
 	const headers: Record<string, string> = {
@@ -474,11 +475,11 @@ export async function requestOpenAiRemoteCompaction(
 		headers[OPENAI_HEADERS.ORIGINATOR] = OPENAI_HEADER_VALUES.ORIGINATOR_CODEX;
 	}
 
-	const response = await fetch(endpoint, {
+	const response = await (opts?.fetch ?? fetch)(endpoint, {
 		method: "POST",
 		headers,
 		body: JSON.stringify(request),
-		signal,
+		signal: withRequestTimeout(signal, opts?.timeoutMs ?? REMOTE_COMPACTION_TIMEOUT_MS),
 	});
 
 	if (!response.ok) {
@@ -489,7 +490,13 @@ export async function requestOpenAiRemoteCompaction(
 			statusText: response.statusText,
 			errorText,
 		});
-		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
+		throw new ProviderHttpError(
+			`Remote compaction failed (${response.status} ${response.statusText})`,
+			response.status,
+			{
+				headers: response.headers,
+			},
+		);
 	}
 
 	const data = (await response.json()) as { output?: unknown[] } | undefined;
@@ -524,12 +531,13 @@ export async function requestRemoteCompaction(
 	endpoint: string,
 	request: RemoteCompactionRequest,
 	signal?: AbortSignal,
+	opts?: { fetch?: FetchImpl; timeoutMs?: number },
 ): Promise<RemoteCompactionResponse> {
-	const response = await fetch(endpoint, {
+	const response = await (opts?.fetch ?? fetch)(endpoint, {
 		method: "POST",
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify(request),
-		signal,
+		signal: withRequestTimeout(signal, opts?.timeoutMs ?? REMOTE_COMPACTION_TIMEOUT_MS),
 	});
 
 	if (!response.ok) {
@@ -540,7 +548,13 @@ export async function requestRemoteCompaction(
 			statusText: response.statusText,
 			errorText,
 		});
-		throw new Error(`Remote compaction failed (${response.status} ${response.statusText})`);
+		throw new ProviderHttpError(
+			`Remote compaction failed (${response.status} ${response.statusText})`,
+			response.status,
+			{
+				headers: response.headers,
+			},
+		);
 	}
 
 	const data = (await response.json()) as RemoteCompactionResponse | undefined;

package/src/compaction/prompts/branch-summary.md

@@ -4,7 +4,7 @@ You MUST use EXACT format:
 
 ## Goal
 
-[What user trying to accomplish in this branch?]
+[What is the user trying to accomplish in this branch?]
 
 ## Constraints & Preferences
 - [Constraints, preferences, requirements mentioned]

package/src/compaction/prompts/compaction-summary-context.md

@@ -1,4 +1,4 @@
-Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. You MUST use this to build on the work that has already been done and NEVER duplicate work. Here is the summary produced by the other language model; you MUST use the information in this summary to assist with your own analysis:
+Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that model used. You MUST build on the work already done and NEVER duplicate it. Here is that summary:
 
 <summary>
 {{summary}}

package/src/compaction/prompts/compaction-summary.md

@@ -1,6 +1,6 @@
-You MUST summarize the conversation above into a structured context checkpoint handoff summary for another LLM to resume task.
+You MUST summarize the conversation above into a structured handoff summary for another LLM to resume the task.
 
-IMPORTANT: If conversation ends with unanswered question to user or imperative/request awaiting user response (e.g., "Please run command and paste output"), you MUST preserve that exact question/request.
+IMPORTANT: If the conversation ends with an unanswered question or a request awaiting user response (e.g., "Please run command and paste output"), you MUST preserve that exact question/request.
 
 You MUST use this format (sections can be omitted if not applicable):
 

package/src/compaction/prompts/compaction-update-summary.md

@@ -1,13 +1,13 @@
-You MUST incorporate new messages above into the existing handoff summary in <previous-summary> tags, used by another LLM to resume task.
+You MUST incorporate the new messages above into the existing handoff summary in <previous-summary> tags, used by another LLM to resume the task.
 RULES:
-- MUST preserve all information from previous summary
+- MUST preserve all information from the previous summary
 - MUST add new progress, decisions, and context from new messages
 - MUST update Progress: move items from "In Progress" to "Done" when completed
 - MUST update "Next Steps" based on what was accomplished
 - MUST preserve exact file paths, function names, and error messages
 - You MAY remove anything no longer relevant
 
-IMPORTANT: If new messages end with unanswered question or request to user, you MUST add it to Critical Context (replacing any previous pending question if answered).
+IMPORTANT: If the new messages end with an unanswered question or request to the user, you MUST add it to Critical Context (replacing any previous pending question if answered).
 
 You MUST use this format (omit sections if not applicable):
 

package/src/compaction/prompts/file-operations.md

@@ -1,10 +1,5 @@
-{{#if readFiles.length}}
-{{#xml "read-files"}}
-{{join readFiles "\n"}}
-{{/xml}}
-{{/if}}
-{{#if modifiedFiles.length}}
-{{#xml "modified-files"}}
-{{join modifiedFiles "\n"}}
+{{#if files}}
+{{#xml "files"}}
+{{files}}
 {{/xml}}
 {{/if}}

package/src/compaction/prompts/summarization-system.md

@@ -1,3 +1,3 @@
 Summarize conversations between users and AI coding assistants. Produce structured summaries in the exact specified format.
 
-Do NOT continue the conversation. Do NOT respond to questions in the conversation. Output ONLY the structured summary.
+NEVER continue the conversation. NEVER respond to questions in it. Output ONLY the structured summary.

package/src/compaction/pruning.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ToolResultMessage } from "@prometheus-ai/ai";
-import type { AgentMessage } from "../types";
+import type { AgentMessage, AgentToolCall } from "../types";
 import { estimateTokens } from "./compaction";
 import type { SessionEntry, SessionMessageEntry } from "./entries";
 import {
@@ -12,6 +12,7 @@ import {
 	isSkillReadToolResult,
 	type ProtectedToolMatcher,
 } from "./tool-protection";
+import { splitReadSelector } from "./utils";
 
 export interface PruneConfig {
 	/** Keep the most recent tool output tokens intact. */
@@ -20,12 +21,22 @@ export interface PruneConfig {
 	minimumSavings: number;
 	/** Tool-result protection matchers. String entries protect every result from that tool; predicates may inspect the paired tool call. */
 	protectedTools: ProtectedToolMatcher[];
+	/**
+	 * Optional supersede key function (see {@link SupersedePruneConfig.supersedeKey}).
+	 * When provided, superseded tool results are pruned first — even inside the
+	 * `protectTokens` window — before age-based victims. Absent, behavior is
+	 * unchanged.
+	 */
+	supersedeKey?: SupersedeKeyFn;
+	/** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
+	pruneUseless?: boolean;
 }
 
 export const DEFAULT_PRUNE_CONFIG: PruneConfig = {
 	protectTokens: 40_000,
 	minimumSavings: 20_000,
 	protectedTools: ["skill", isSkillReadToolResult],
+	pruneUseless: true,
 };
 
 export interface PruneResult {
@@ -33,6 +44,39 @@ export interface PruneResult {
 	tokensSaved: number;
 }
 
+/** Exact placeholder written over a superseded tool result. */
+export const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
+
+/** Exact placeholder written over an elided useless tool result. */
+export const USELESS_NOTICE = "[Uneventful result elided]";
+
+/**
+ * Maps a tool call to a supersede key. Results sharing a key form a group in
+ * which every result except the newest is a supersede candidate. A key `K`
+ * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
+ * supersedes selector-carrying reads of the same base path). Return
+ * `undefined` to exempt a call from supersede grouping.
+ */
+export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
+
+export interface SupersedePruneConfig {
+	/** Supersede key function; results sharing a key supersede older ones. */
+	supersedeKey?: SupersedeKeyFn;
+	/** Also prune results flagged useless by their tool. Default false. */
+	pruneUseless?: boolean;
+	/** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
+	suffixTokenLimit?: number;
+	/** Prune all candidates when the last message is at least this old (prompt cache is cold anyway). Default 30 min. */
+	idleFlushMs?: number;
+	/** Clock override for tests. */
+	now?: number;
+	/** Tool-result protection matchers (same contract as {@link PruneConfig.protectedTools}). */
+	protectedTools: ProtectedToolMatcher[];
+}
+
+const DEFAULT_SUFFIX_TOKEN_LIMIT = 8_000;
+const DEFAULT_IDLE_FLUSH_MS = 30 * 60_000;
+
 function createPrunedNotice(tokens: number): string {
 	return `[Output truncated - ${tokens} tokens]`;
 }
@@ -44,18 +88,169 @@ function getToolResultMessage(entry: SessionEntry): ToolResultMessage | undefine
 	return message as ToolResultMessage;
 }
 
-function estimatePrunedSavings(tokens: number): number {
-	const noticeTokens = Math.ceil(createPrunedNotice(tokens).length / 4);
+function estimatePrunedSavings(tokens: number, notice: string): number {
+	const noticeTokens = Math.ceil(notice.length / 4);
 	return Math.max(0, tokens - noticeTokens);
 }
 
+interface SupersedeCandidate {
+	entry: SessionMessageEntry;
+	message: ToolResultMessage;
+	/** Index of the entry within the `entries` array. */
+	index: number;
+	tokens: number;
+	/** Placeholder text written over the blanked result. */
+	notice: string;
+}
+
+/**
+ * Collect superseded tool results: for every unpruned, unprotected tool result
+ * whose paired call resolves a supersede key, a LATER result with the same key
+ * — or with a key that is the `"\u0000"`-prefix parent of this one — marks it
+ * superseded. Returned in message order.
+ */
+function collectSupersededResults(
+	entries: readonly SessionEntry[],
+	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	supersedeKey: SupersedeKeyFn,
+	protectedTools: readonly ProtectedToolMatcher[],
+): SupersedeCandidate[] {
+	const candidates: SupersedeCandidate[] = [];
+	const seenKeys = new Set<string>();
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (!message || message.prunedAt !== undefined) continue;
+		const toolCall = toolCallsById.get(message.toolCallId);
+		if (!toolCall) continue;
+		if (isProtectedToolResult(message, toolCall, protectedTools)) continue;
+		const key = supersedeKey(toolCall.name, toolCall.arguments as Record<string, unknown>);
+		if (key === undefined) continue;
+		const separator = key.indexOf("\u0000");
+		const superseded = seenKeys.has(key) || (separator >= 0 && seenKeys.has(key.slice(0, separator)));
+		seenKeys.add(key);
+		if (!superseded) continue;
+		candidates.push({
+			entry: entry as SessionMessageEntry,
+			message,
+			index: i,
+			tokens: estimateTokens(message as AgentMessage),
+			notice: SUPERSEDED_NOTICE,
+		});
+	}
+	return candidates.reverse();
+}
+
+/**
+ * Collect tool results their tool flagged contextually useless (zero matches,
+ * elapsed wait): unpruned, non-error, unprotected, not in `exclude`, and large
+ * enough that blanking to {@link USELESS_NOTICE} actually saves tokens.
+ * Returned in message order.
+ */
+function collectUselessResults(
+	entries: readonly SessionEntry[],
+	toolCallsById: ReadonlyMap<string, AgentToolCall>,
+	protectedTools: readonly ProtectedToolMatcher[],
+	exclude: ReadonlySet<ToolResultMessage>,
+): SupersedeCandidate[] {
+	const candidates: SupersedeCandidate[] = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		const message = getToolResultMessage(entry);
+		if (message?.useless !== true || message.prunedAt !== undefined || message.isError === true) continue;
+		if (exclude.has(message)) continue;
+		if (isProtectedToolResult(message, toolCallsById.get(message.toolCallId), protectedTools)) continue;
+		const tokens = estimateTokens(message as AgentMessage);
+		if (estimatePrunedSavings(tokens, USELESS_NOTICE) <= 0) continue;
+		candidates.push({ entry: entry as SessionMessageEntry, message, index: i, tokens, notice: USELESS_NOTICE });
+	}
+	return candidates;
+}
+
+/**
+ * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
+ * read of the same file) and, when `pruneUseless` is set, results their tool
+ * flagged contextually useless. Cheap, incremental, and prompt-cache-aware: a
+ * candidate is pruned now only when the suffix after it is small (tail case —
+ * the read→edit→read loop) or when the context has been idle long enough that
+ * the provider cache is cold anyway (then ALL candidates flush).
+ */
+export function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult {
+	const toolCallsById = collectToolCallsById(entries);
+	const candidates = config.supersedeKey
+		? collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools)
+		: [];
+	if (config.pruneUseless) {
+		const exclude = new Set(candidates.map(candidate => candidate.message));
+		candidates.push(...collectUselessResults(entries, toolCallsById, config.protectedTools, exclude));
+		candidates.sort((a, b) => a.index - b.index);
+	}
+	if (candidates.length === 0) return { prunedCount: 0, tokensSaved: 0 };
+
+	const now = config.now ?? Date.now();
+	let lastMessageTimestamp: number | undefined;
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type !== "message") continue;
+		const timestamp = (entry.message as AgentMessage).timestamp;
+		if (typeof timestamp === "number") lastMessageTimestamp = timestamp;
+		break;
+	}
+	const idle =
+		lastMessageTimestamp !== undefined && now - lastMessageTimestamp >= (config.idleFlushMs ?? DEFAULT_IDLE_FLUSH_MS);
+
+	let toPrune: SupersedeCandidate[];
+	if (idle) {
+		toPrune = candidates;
+	} else {
+		const suffixTokenLimit = config.suffixTokenLimit ?? DEFAULT_SUFFIX_TOKEN_LIMIT;
+		// suffixTokens[i] = estimated tokens of all messages strictly after entry i.
+		const suffixTokens = new Array<number>(entries.length);
+		let accumulated = 0;
+		for (let i = entries.length - 1; i >= 0; i--) {
+			suffixTokens[i] = accumulated;
+			const entry = entries[i];
+			if (entry.type === "message") accumulated += estimateTokens(entry.message as AgentMessage);
+		}
+		toPrune = candidates.filter(candidate => suffixTokens[candidate.index] <= suffixTokenLimit);
+	}
+	if (toPrune.length === 0) return { prunedCount: 0, tokensSaved: 0 };
+
+	const prunedAt = Date.now();
+	let tokensSaved = 0;
+	for (const candidate of toPrune) {
+		candidate.message.content = [{ type: "text", text: candidate.notice }];
+		candidate.message.prunedAt = prunedAt;
+		tokensSaved += estimatePrunedSavings(candidate.tokens, candidate.notice);
+	}
+	return { prunedCount: toPrune.length, tokensSaved };
+}
+
 export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
 	let accumulatedTokens = 0;
 	let tokensSaved = 0;
 	let prunedCount = 0;
 
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number }> = [];
+	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; superseded: boolean; useless: boolean }> = [];
 	const toolCallsById = collectToolCallsById(entries);
+	const supersededMessages = config.supersedeKey
+		? new Set(
+				collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools).map(
+					candidate => candidate.message,
+				),
+			)
+		: undefined;
+	const uselessMessages =
+		config.pruneUseless !== false
+			? new Set(
+					collectUselessResults(
+						entries,
+						toolCallsById,
+						config.protectedTools,
+						supersededMessages ?? new Set(),
+					).map(candidate => candidate.message),
+				)
+			: undefined;
 
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
@@ -70,17 +265,30 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 			continue;
 		}
 
-		if (accumulatedTokens < config.protectTokens || isProtected) {
+		// Superseded and useless results are pruned first: they bypass the
+		// protect window (a stale copy of re-read content — or a result the
+		// tool itself flagged as carrying no information — is dead weight at
+		// any age).
+		const superseded = supersededMessages?.has(message) ?? false;
+		const useless = uselessMessages?.has(message) ?? false;
+		if (!superseded && !useless && (accumulatedTokens < config.protectTokens || isProtected)) {
 			accumulatedTokens += tokens;
 			continue;
 		}
 
-		candidates.push({ entry: entry as SessionMessageEntry, tokens });
+		candidates.push({ entry: entry as SessionMessageEntry, tokens, superseded, useless });
 		accumulatedTokens += tokens;
 	}
 
 	for (const candidate of candidates) {
-		tokensSaved += estimatePrunedSavings(candidate.tokens);
+		tokensSaved += estimatePrunedSavings(
+			candidate.tokens,
+			candidate.superseded
+				? SUPERSEDED_NOTICE
+				: candidate.useless
+					? USELESS_NOTICE
+					: createPrunedNotice(candidate.tokens),
+		);
 	}
 
 	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
@@ -90,10 +298,34 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	const prunedAt = Date.now();
 	for (const candidate of candidates) {
 		const message = candidate.entry.message as ToolResultMessage;
-		message.content = [{ type: "text", text: createPrunedNotice(candidate.tokens) }];
+		const notice = candidate.superseded
+			? SUPERSEDED_NOTICE
+			: candidate.useless
+				? USELESS_NOTICE
+				: createPrunedNotice(candidate.tokens);
+		message.content = [{ type: "text", text: notice }];
 		message.prunedAt = prunedAt;
 		prunedCount++;
 	}
 
 	return { prunedCount, tokensSaved };
 }
+
+/**
+ * Supersede key for the `read` tool: the file path with the trailing line/raw
+ * selector stripped (the read tool's own splitter grammar via
+ * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
+ * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
+ * Selector-free reads key on the bare path; selector-carrying reads key on
+ * `path + "\u0000" + selector`, so two reads collide only when the newer is
+ * selector-free or the selectors are identical (the pass's prefix rule lets a
+ * bare-path read supersede selector-carrying reads of the same file).
+ */
+export function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined {
+	if (toolName !== "read") return undefined;
+	const path = args.path;
+	if (typeof path !== "string" || path.length === 0) return undefined;
+	if (path.includes("://")) return undefined;
+	const { path: base, sel } = splitReadSelector(path);
+	return sel === undefined ? base : `${base}\u0000${sel}`;
+}