@oh-my-pi/pi-agent-core 15.11.8 → 15.12.1

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [15.12.1] - 2026-06-12
+### Breaking Changes
+
+- Changed `pruneSupersededToolResults` to allow `supersedeKey` to be omitted so useless-result pruning can run without read-style supersede grouping
+
+### Added
+
+- Added `pruneUseless` controls to `PruneConfig` and `SupersedePruneConfig` so callers can toggle compaction of `toolResult` entries marked `useless`
+- Added the ability to disable useless-result pruning by setting `pruneUseless` to false
+- Tools can flag a result contextually useless (`AgentToolResult.useless`; overridable via `AfterToolCallResult.useless`): the agent loop copies the flag onto the persisted `ToolResultMessage` (errors always win), and compaction consumes it — the cache-aware supersede pass and the threshold prune blank flagged results to the exact `USELESS_NOTICE` placeholder (bypassing the protect window, skipping results smaller than the notice), shake collects them inside the protect-recent window, and `serializeConversation` drops the whole tool call/result pair from summarizer input
+
+### Changed
+
+- Changed `pruneSupersededToolResults` to allow omitted `supersedeKey` when `pruneUseless` is enabled, so useless-result pruning can run without read-style supersede grouping
+
 ## [15.11.4] - 2026-06-12
 ### Added
 

package/dist/types/compaction/pruning.d.ts

@@ -17,6 +17,8 @@ export interface PruneConfig {
      * unchanged.
      */
     supersedeKey?: SupersedeKeyFn;
+    /** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
+    pruneUseless?: boolean;
 }
 export declare const DEFAULT_PRUNE_CONFIG: PruneConfig;
 export interface PruneResult {
@@ -25,6 +27,8 @@ export interface PruneResult {
 }
 /** Exact placeholder written over a superseded tool result. */
 export declare const SUPERSEDED_NOTICE = "[Superseded by a newer read of this file]";
+/** Exact placeholder written over an elided useless tool result. */
+export declare 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`
@@ -35,7 +39,9 @@ export declare const SUPERSEDED_NOTICE = "[Superseded by a newer read of this fi
 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;
+    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. */
@@ -47,7 +53,8 @@ export interface SupersedePruneConfig {
 }
 /**
  * Prune superseded tool results (e.g. stale `read` outputs replaced by a newer
- * read of the same file). Cheap, incremental, and prompt-cache-aware: a
+ * 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).

package/dist/types/compaction/shake.d.ts

@@ -54,7 +54,9 @@ export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
  * Walks the protect-recent window (most recent `protectTokens` of context is
  * kept intact), collects whole tool-result messages (honoring `protectedTools`
  * and skipping already-pruned results) and large fenced/XML blocks inside
- * user/developer/assistant/custom messages. Returns regions in document order.
+ * user/developer/assistant/custom messages. Tool results flagged contextually
+ * useless by their tool bypass the protect window — there is nothing recent
+ * worth keeping in them. Returns regions in document order.
  *
  * `toolCall` blocks are never touched (tool-call/result pairing is preserved)
  * and regions never span a message boundary. When the combined estimated

package/dist/types/types.d.ts

@@ -277,6 +277,8 @@ export interface AfterToolCallResult {
     details?: unknown;
     /** If provided, replaces the error flag carried with the tool result. */
     isError?: boolean;
+    /** If provided, replaces the contextually-useless flag carried with the tool result. */
+    useless?: boolean;
 }
 /** Context passed to `beforeToolCall`. */
 export interface BeforeToolCallContext {
@@ -348,6 +350,8 @@ export interface AgentToolResult<T = any, _TInput = unknown> {
     content: (TextContent | ImageContent)[];
     details?: T;
     isError?: boolean;
+    /** Marks the result as contextually useless: safe for compaction to elide once consumed (e.g. zero matches, wait timeout). Ignored when isError is set. */
+    useless?: boolean;
 }
 export type AgentToolUpdateCallback<T = any, TInput = unknown> = (partialResult: AgentToolResult<T, TInput>) => void;
 /** Options passed to renderResult */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "15.11.8",
+	"version": "15.12.1",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,11 +35,11 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "15.11.8",
-		"@oh-my-pi/pi-catalog": "15.11.8",
-		"@oh-my-pi/pi-natives": "15.11.8",
-		"@oh-my-pi/pi-utils": "15.11.8",
-		"@oh-my-pi/snapcompact": "15.11.8",
+		"@oh-my-pi/pi-ai": "15.12.1",
+		"@oh-my-pi/pi-catalog": "15.12.1",
+		"@oh-my-pi/pi-natives": "15.12.1",
+		"@oh-my-pi/pi-utils": "15.12.1",
+		"@oh-my-pi/snapcompact": "15.12.1",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -174,6 +174,9 @@ function coerceToolResult(raw: unknown): { result: AgentToolResult<unknown>; mal
 	// aggregator that catches per-entry errors and synthesizes a combined
 	// result). Preserve the flag so agent-loop can surface it on the wire.
 	const explicitError = Boolean(rawObj && "isError" in rawObj && rawObj.isError);
+	// Tools may flag the result contextually useless (zero matches, elapsed
+	// wait) so compaction can elide it once consumed. Errors are never useless.
+	const useless = Boolean(rawObj && "useless" in rawObj && rawObj.useless);
 
 	if (!Array.isArray(rawContent)) {
 		return {
@@ -218,7 +221,12 @@ function coerceToolResult(raw: unknown): { result: AgentToolResult<unknown>; mal
 		content.push({ type: "text", text: EMPTY_ERROR_TOOL_RESULT_TEXT });
 	}
 	return {
-		result: { content, details, ...(isError ? { isError: true } : {}) },
+		result: {
+			content,
+			details,
+			...(isError ? { isError: true } : {}),
+			...(useless && !isError ? { useless: true } : {}),
+		},
 		malformed: invalidBlocks > 0,
 	};
 }
@@ -1355,6 +1363,7 @@ async function executeToolCalls(
 			content: result.content,
 			details: result.details,
 			isError,
+			...(result.useless && !isError ? { useless: true } : {}),
 			timestamp: Date.now(),
 		};
 		record.result = result;
@@ -1534,6 +1543,7 @@ async function executeToolCalls(
 							content: after.content ?? result.content,
 							details: after.details ?? result.details,
 							isError: after.isError ?? result.isError,
+							useless: after.useless ?? result.useless,
 						});
 						result = coerced.result;
 						isError = coerced.malformed || (after.isError ?? isError);

package/src/compaction/pruning.ts

@@ -28,12 +28,15 @@ export interface PruneConfig {
 	 * 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 {
@@ -44,6 +47,9 @@ export interface PruneResult {
 /** 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`
@@ -55,7 +61,9 @@ export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) =
 
 export interface SupersedePruneConfig {
 	/** Supersede key function; results sharing a key supersede older ones. */
-	supersedeKey: SupersedeKeyFn;
+	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. */
@@ -91,6 +99,8 @@ interface SupersedeCandidate {
 	/** Index of the entry within the `entries` array. */
 	index: number;
 	tokens: number;
+	/** Placeholder text written over the blanked result. */
+	notice: string;
 }
 
 /**
@@ -125,21 +135,56 @@ function collectSupersededResults(
 			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). Cheap, incremental, and prompt-cache-aware: a
+ * 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 = collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools);
+	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();
@@ -174,9 +219,9 @@ export function pruneSupersededToolResults(entries: SessionEntry[], config: Supe
 	const prunedAt = Date.now();
 	let tokensSaved = 0;
 	for (const candidate of toPrune) {
-		candidate.message.content = [{ type: "text", text: SUPERSEDED_NOTICE }];
+		candidate.message.content = [{ type: "text", text: candidate.notice }];
 		candidate.message.prunedAt = prunedAt;
-		tokensSaved += estimatePrunedSavings(candidate.tokens, SUPERSEDED_NOTICE);
+		tokensSaved += estimatePrunedSavings(candidate.tokens, candidate.notice);
 	}
 	return { prunedCount: toPrune.length, tokensSaved };
 }
@@ -186,7 +231,7 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	let tokensSaved = 0;
 	let prunedCount = 0;
 
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; superseded: boolean }> = [];
+	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; superseded: boolean; useless: boolean }> = [];
 	const toolCallsById = collectToolCallsById(entries);
 	const supersededMessages = config.supersedeKey
 		? new Set(
@@ -195,6 +240,17 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 				),
 			)
 		: 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];
@@ -209,22 +265,29 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 			continue;
 		}
 
-		// Superseded results are pruned first: they bypass the protect window
-		// (a stale copy of re-read content is dead weight at any age).
+		// 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;
-		if (!superseded && (accumulatedTokens < config.protectTokens || isProtected)) {
+		const useless = uselessMessages?.has(message) ?? false;
+		if (!superseded && !useless && (accumulatedTokens < config.protectTokens || isProtected)) {
 			accumulatedTokens += tokens;
 			continue;
 		}
 
-		candidates.push({ entry: entry as SessionMessageEntry, tokens, superseded });
+		candidates.push({ entry: entry as SessionMessageEntry, tokens, superseded, useless });
 		accumulatedTokens += tokens;
 	}
 
 	for (const candidate of candidates) {
 		tokensSaved += estimatePrunedSavings(
 			candidate.tokens,
-			candidate.superseded ? SUPERSEDED_NOTICE : createPrunedNotice(candidate.tokens),
+			candidate.superseded
+				? SUPERSEDED_NOTICE
+				: candidate.useless
+					? USELESS_NOTICE
+					: createPrunedNotice(candidate.tokens),
 		);
 	}
 
@@ -235,9 +298,12 @@ 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: candidate.superseded ? SUPERSEDED_NOTICE : 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++;
 	}

package/src/compaction/shake.ts

@@ -267,7 +267,9 @@ function scanContentBlocks(
  * Walks the protect-recent window (most recent `protectTokens` of context is
  * kept intact), collects whole tool-result messages (honoring `protectedTools`
  * and skipping already-pruned results) and large fenced/XML blocks inside
- * user/developer/assistant/custom messages. Returns regions in document order.
+ * user/developer/assistant/custom messages. Tool results flagged contextually
+ * useless by their tool bypass the protect window — there is nothing recent
+ * worth keeping in them. Returns regions in document order.
  *
  * `toolCall` blocks are never touched (tool-call/result pairing is preserved)
  * and regions never span a message boundary. When the combined estimated
@@ -289,10 +291,12 @@ export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig
 
 	const regions: ShakeRegion[] = [];
 	for (let i = 0; i < n; i++) {
-		if (accumulatedAfter[i] < config.protectTokens) continue;
 		const entry = entries[i];
-
 		const toolResult = getToolResultMessage(entry);
+		// Useless-flagged results carry no information once consumed; they are
+		// eligible even inside the protect-recent window.
+		const uselessResult = toolResult !== undefined && toolResult.useless === true && toolResult.isError !== true;
+		if (!uselessResult && accumulatedAfter[i] < config.protectTokens) continue;
 		if (toolResult) {
 			if (toolResult.prunedAt !== undefined) continue;
 			if (isProtectedToolResult(toolResult, toolCallsById.get(toolResult.toolCallId), config.protectedTools))

package/src/compaction/utils.ts

@@ -191,6 +191,17 @@ function truncateForSummary(text: string, maxChars: number): string {
 export function serializeConversation(messages: Message[]): string {
 	const parts: string[] = [];
 
+	// Tool results flagged contextually useless (and their paired calls) are
+	// dropped from the serialized text: the source region is discarded after
+	// summarization anyway, so excluding them costs nothing and keeps garbage
+	// out of the summary input.
+	const uselessCallIds = new Set<string>();
+	for (const msg of messages) {
+		if (msg.role === "toolResult" && msg.useless === true && msg.isError !== true) {
+			uselessCallIds.add(msg.toolCallId);
+		}
+	}
+
 	for (const msg of messages) {
 		if (msg.role === "user") {
 			const content =
@@ -212,6 +223,7 @@ export function serializeConversation(messages: Message[]): string {
 				} else if (block.type === "thinking") {
 					thinkingParts.push(block.thinking);
 				} else if (block.type === "toolCall") {
+					if (uselessCallIds.has(block.id)) continue;
 					const args = block.arguments as Record<string, unknown>;
 					const argsStr = Object.entries(args)
 						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
@@ -230,6 +242,7 @@ export function serializeConversation(messages: Message[]): string {
 				parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
 			}
 		} else if (msg.role === "toolResult") {
+			if (uselessCallIds.has(msg.toolCallId)) continue;
 			const content = msg.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")
 				.map(c => c.text)

package/src/types.ts

@@ -326,6 +326,8 @@ export interface AfterToolCallResult {
 	details?: unknown;
 	/** If provided, replaces the error flag carried with the tool result. */
 	isError?: boolean;
+	/** If provided, replaces the contextually-useless flag carried with the tool result. */
+	useless?: boolean;
 }
 
 /** Context passed to `beforeToolCall`. */
@@ -408,6 +410,8 @@ export interface AgentToolResult<T = any, _TInput = unknown> {
 	// Marks a non-throwing failure (e.g. an aggregator catching per-entry errors).
 	// agent-loop honors this and surfaces it as a tool error on the wire.
 	isError?: boolean;
+	/** Marks the result as contextually useless: safe for compaction to elide once consumed (e.g. zero matches, wait timeout). Ignored when isError is set. */
+	useless?: boolean;
 }
 
 // Callback for streaming tool execution updates