feat(compaction): microcompaction — clear stale tool results before summarizing

Our compaction was single-tier: at 75% of the window it ran the
glue-model summarize-everything sledgehammer. Now a cheap first pass
runs first — microcompaction clears the CONTENT of stale tool-result
messages (old read_file/grep/glob/shell/web/edit output the model
already consumed) while keeping the newest 6 intact and preserving
message structure, so tool_use/tool_result pairing isn't broken and no
glue call happens.

transformContext now: needsCompaction → microcompact → if that alone
drops us back under threshold, done (no summary); else fall through to
the full summarize path operating on the already-cleared messages.

Adapts Claude Code's COMPACTABLE_TOOLS + content-clear mechanic to our
proxy/any-model setup — CC's two triggers (cache_edits API, cold-cache
time-based) are Anthropic-cache-specific, so ours is token-pressure
triggered instead. Errored results are kept (short, valuable as
debugging signal); the pass is idempotent. 7 microcompact tests + an
engine test proving microcompact frees tokens with zero glue calls.

Author: halfaipg

src/agent/agent.ts

@@ -114,9 +114,7 @@ export interface AgentBundle {
 	 * veto. Callers that originate prompts from real user input should use
 	 * this instead of `agent.prompt()` directly.
 	 */
-	submitUserPrompt: (
-		text: string,
-	) => Promise<{ submitted: boolean; reason?: string; error?: string }>;
+	submitUserPrompt: (text: string) => Promise<{ submitted: boolean; reason?: string; error?: string }>;
 	/**
 	 * Set when `--resume` actually loaded a prior session, with its
 	 * timestamp + message count so the welcome banner can say
@@ -228,7 +226,10 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	// project's conventions on every turn. Memory addendum is appended
 	// after — it's the user's accumulated long-term notes.
 	const fullSystemPrompt =
-		systemPrompt + buildProjectFilesAddendum(cwd) + buildMemoryAddendum(memory) + buildOutputStyleAddendum(persistedConfig, cwd);
+		systemPrompt +
+		buildProjectFilesAddendum(cwd) +
+		buildMemoryAddendum(memory) +
+		buildOutputStyleAddendum(persistedConfig, cwd);
 
 	const agent = new Agent({
 		initialState: {
@@ -240,14 +241,28 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 		getApiKey: () => apiKey,
 		transformContext: async (messages, signal) => {
 			if (!compaction.needsCompaction(messages)) return messages;
-			compactionMonitor.start(messages.length);
+
+			// Stage 1 — microcompaction: clear stale tool-result content
+			// (old reads, grep dumps, command output) without a summary
+			// round-trip. Cheap. If that alone drops us back under the
+			// threshold, we're done and skip the expensive summarize path.
+			const micro = compaction.microcompact(messages);
+			if (micro.clearedCount > 0 && !compaction.needsCompaction(micro.messages)) {
+				return micro.messages;
+			}
+			// Microcompaction wasn't enough (or freed nothing) — fall through
+			// to the full summarize-everything compaction, operating on the
+			// already-cleared messages so the summary input is smaller too.
+			const working = micro.messages;
+
+			compactionMonitor.start(working.length);
 			try {
 				await hooks.dispatch(
 					"PreCompact",
-					{ event: "PreCompact", workingDir: cwd, messageCount: messages.length },
+					{ event: "PreCompact", workingDir: cwd, messageCount: working.length },
 					signal,
 				);
-				const result = await compaction.compact(messages, signal);
+				const result = await compaction.compact(working, signal);
 				await hooks.dispatch(
 					"PostCompact",
 					{
@@ -419,9 +434,7 @@ export function createAgent(opts: CreateAgentOptions = {}): AgentBundle {
 	 * accepted the prompt. The agent's own turn lifecycle still emits
 	 * events on bundle.subscribe.
 	 */
-	const submitUserPrompt = async (
-		text: string,
-	): Promise<{ submitted: boolean; reason?: string; error?: string }> => {
+	const submitUserPrompt = async (text: string): Promise<{ submitted: boolean; reason?: string; error?: string }> => {
 		const outcome = await hooks.dispatch("UserPromptSubmit", {
 			event: "UserPromptSubmit",
 			workingDir: cwd,

src/compaction/engine.test.ts

@@ -222,4 +222,22 @@ describe("CompactionEngine", () => {
 		const result = await engine.compact(messages);
 		expect(result.details.summary).toMatch(/summarization failed/);
 	});
+
+	it("microcompact clears stale tool-result content without a glue call", () => {
+		const glue = fakeGlue("should not be called");
+		const engine = new CompactionEngine({ glue, modelId: "claude-sonnet-4-6" });
+		const big = "x".repeat(4000);
+		const messages: AgentMessage[] = [];
+		for (let i = 0; i < 10; i++) {
+			messages.push(toolCallMessage("read_file", `tc${i}`, { path: `f${i}.ts` }));
+			messages.push(toolResultMessage(`tc${i}`, "read_file", `${big} #${i}`));
+		}
+		const before = estimateTotalTokens(messages);
+		const out = engine.microcompact(messages);
+		expect(out.clearedCount).toBeGreaterThan(0);
+		expect(out.tokensSaved).toBeGreaterThan(0);
+		expect(estimateTotalTokens(out.messages)).toBeLessThan(before);
+		// Microcompaction never summarizes — glue must not be touched.
+		expect(glue.smart).not.toHaveBeenCalled();
+	});
 });

src/compaction/engine.ts

@@ -1,10 +1,13 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { GlueClient } from "../glue/client.js";
+import { microcompact } from "./microcompact.js";
 import { contextWindow, estimateMessageTokens, estimateTotalTokens } from "./tokens.js";
-import type { CompactionDetails, CompactionResult } from "./types.js";
+import type { CompactionDetails, CompactionResult, MicrocompactResult } from "./types.js";
 
 const DEFAULT_THRESHOLD = 0.75;
 const DEFAULT_KEEP_RECENT = 8;
+/** Newest compactable tool results microcompaction always keeps intact. */
+const MICRO_KEEP_RECENT = 6;
 
 const SUMMARY_SYSTEM_PROMPT = `Summarize the prior conversation between a user and a coding agent in tight markdown. Output structure:
 
@@ -62,6 +65,21 @@ export class CompactionEngine {
 		return estimateTotalTokens(messages) >= this.threshold();
 	}
 
+	/**
+	 * Cheap first-pass compaction: clear the content of stale tool
+	 * results (old file reads, grep dumps, command output the model
+	 * already consumed) while keeping the newest few and preserving
+	 * message structure. No glue-model round-trip. Returns the rewritten
+	 * messages plus how much was freed.
+	 *
+	 * Exposed so the agent's transformContext can try this before the
+	 * expensive summarize-everything path — clearing tool results often
+	 * relieves the pressure on its own.
+	 */
+	microcompact(messages: AgentMessage[]): MicrocompactResult {
+		return microcompact(messages, MICRO_KEEP_RECENT);
+	}
+
 	async compact(messages: AgentMessage[], signal?: AbortSignal): Promise<CompactionResult> {
 		if (messages.length <= this.keepRecent) {
 			return {

src/compaction/microcompact.test.ts

@@ -0,0 +1,99 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { describe, expect, it } from "vitest";
+import { CLEARED_TOOL_RESULT, microcompact } from "./microcompact.js";
+
+function toolResult(toolName: string, text: string, opts: { isError?: boolean } = {}): AgentMessage {
+	return {
+		role: "toolResult",
+		toolCallId: `tc-${Math.random().toString(36).slice(2)}`,
+		toolName,
+		content: [{ type: "text", text }],
+		isError: opts.isError ?? false,
+		timestamp: 0,
+	} as AgentMessage;
+}
+
+function user(text: string): AgentMessage {
+	return { role: "user", content: text, timestamp: 0 } as AgentMessage;
+}
+
+function clearedText(m: AgentMessage): string | undefined {
+	const content = (m as { content: Array<{ type: string; text?: string }> }).content;
+	return content?.[0]?.text;
+}
+
+describe("microcompact", () => {
+	it("clears stale compactable tool results, keeping the newest N", () => {
+		const big = "x".repeat(5000);
+		const messages: AgentMessage[] = [];
+		for (let i = 0; i < 10; i++) {
+			messages.push(user(`turn ${i}`));
+			messages.push(toolResult("read_file", `${big} #${i}`));
+		}
+		const out = microcompact(messages, 3);
+		// 10 read_file results, keep 3 → clear 7.
+		expect(out.clearedCount).toBe(7);
+		expect(out.tokensSaved).toBeGreaterThan(0);
+
+		// The last 3 tool results retain their content; earlier ones are cleared.
+		const toolResults = out.messages.filter((m) => m.role === "toolResult");
+		const clearedFlags = toolResults.map((m) => clearedText(m) === CLEARED_TOOL_RESULT);
+		expect(clearedFlags.slice(0, 7)).toEqual([true, true, true, true, true, true, true]);
+		expect(clearedFlags.slice(7)).toEqual([false, false, false]);
+	});
+
+	it("preserves message structure (same count, same order, tool results stay tool results)", () => {
+		const messages: AgentMessage[] = [
+			user("a"),
+			toolResult("read_file", "x".repeat(2000)),
+			toolResult("grep", "y".repeat(2000)),
+			toolResult("read_file", "z".repeat(2000)),
+		];
+		const out = microcompact(messages, 1);
+		expect(out.messages).toHaveLength(messages.length);
+		expect(out.messages.map((m) => m.role)).toEqual(["user", "toolResult", "toolResult", "toolResult"]);
+	});
+
+	it("never clears errored tool results", () => {
+		const messages: AgentMessage[] = [
+			toolResult("shell", "boom", { isError: true }),
+			toolResult("read_file", "x".repeat(2000)),
+			toolResult("read_file", "y".repeat(2000)),
+		];
+		const out = microcompact(messages, 0);
+		// keepRecent 0, but the error is exempt → only the two reads clear.
+		expect(out.clearedCount).toBe(2);
+		const err = out.messages[0];
+		expect(clearedText(err)).toBe("boom");
+	});
+
+	it("ignores non-compactable tools (ask_user, tasks, config, git)", () => {
+		const messages: AgentMessage[] = [
+			toolResult("git_status", "branch info"),
+			toolResult("create_task", "task body"),
+			toolResult("config", "{}"),
+		];
+		const out = microcompact(messages, 0);
+		expect(out.clearedCount).toBe(0);
+		expect(out.tokensSaved).toBe(0);
+	});
+
+	it("is idempotent — a second pass clears nothing new", () => {
+		const messages: AgentMessage[] = [
+			toolResult("read_file", "x".repeat(3000)),
+			toolResult("read_file", "y".repeat(3000)),
+			toolResult("read_file", "z".repeat(3000)),
+		];
+		const first = microcompact(messages, 1);
+		expect(first.clearedCount).toBe(2);
+		const second = microcompact(first.messages, 1);
+		expect(second.clearedCount).toBe(0);
+	});
+
+	it("returns the same array unchanged when nothing to clear", () => {
+		const messages: AgentMessage[] = [user("hi"), toolResult("read_file", "small")];
+		const out = microcompact(messages, 6);
+		expect(out.clearedCount).toBe(0);
+		expect(out.messages).toBe(messages);
+	});
+});

src/compaction/microcompact.ts

@@ -0,0 +1,101 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { estimateMessageTokens } from "./tokens.js";
+import type { MicrocompactResult } from "./types.js";
+
+/**
+ * Placeholder swapped in for a cleared tool result. Kept terse and
+ * self-explanatory so the model understands the content is gone but
+ * re-obtainable, without spending tokens describing it.
+ */
+export const CLEARED_TOOL_RESULT =
+	"[Old tool result content cleared — re-read the file or re-run the command if you need it again]";
+
+/**
+ * Tool results worth clearing once they're stale: read-only lookups and
+ * file/command output that the model has already acted on. Deliberately
+ * EXCLUDES tools whose result is small or load-bearing past its turn
+ * (ask_user, tasks, memory, config, git status/diff — those are short
+ * and often re-referenced). Mirrors Claude Code's COMPACTABLE_TOOLS.
+ */
+const COMPACTABLE_TOOLS: ReadonlySet<string> = new Set([
+	"read_file",
+	"shell",
+	"ssh_exec",
+	"grep",
+	"glob",
+	"list_files",
+	"web_fetch",
+	"web_search",
+	"edit_file",
+	"multi_edit",
+	"write_file",
+]);
+
+const DEFAULT_KEEP_RECENT = 6;
+
+/**
+ * Microcompaction: clear the CONTENT of stale tool-result messages while
+ * keeping the message itself (so the tool_use/tool_result pairing stays
+ * intact and the provider doesn't reject the transcript). The newest
+ * `keepRecent` compactable results are left untouched — they're the
+ * model's live working set.
+ *
+ * This is the cheap first line of defense against context pressure: a
+ * repo-wide grep dump or a big file read the model already consumed gets
+ * its bytes reclaimed WITHOUT a glue-model summary round-trip. The
+ * expensive summarize-everything compaction stays as the fallback for
+ * when clearing tool results alone isn't enough.
+ *
+ * Errored results are preserved — they're short and usually still
+ * relevant as debugging signal. Already-cleared results are skipped so
+ * the pass is idempotent.
+ */
+export function microcompact(messages: AgentMessage[], keepRecent = DEFAULT_KEEP_RECENT): MicrocompactResult {
+	// First pass: index every compactable, not-yet-cleared tool-result
+	// message in order.
+	const indices: number[] = [];
+	for (let i = 0; i < messages.length; i++) {
+		const m = messages[i];
+		if (m.role !== "toolResult") continue;
+		const tr = m as ToolResultMessage;
+		if (tr.isError) continue;
+		if (!COMPACTABLE_TOOLS.has(tr.toolName)) continue;
+		if (isAlreadyCleared(tr)) continue;
+		indices.push(i);
+	}
+
+	// Keep the most-recent `keepRecent`; clear the rest.
+	const keep = Math.max(0, keepRecent);
+	const clearIdx = new Set(indices.slice(0, Math.max(0, indices.length - keep)));
+	if (clearIdx.size === 0) {
+		return { messages, tokensSaved: 0, clearedCount: 0 };
+	}
+
+	let tokensSaved = 0;
+	const next = messages.map((m, i) => {
+		if (!clearIdx.has(i)) return m;
+		const tr = m as ToolResultMessage;
+		const before = estimateMessageTokens(m);
+		const cleared: ToolResultMessage = {
+			...tr,
+			content: [{ type: "text", text: CLEARED_TOOL_RESULT }],
+		};
+		tokensSaved += before - estimateMessageTokens(cleared as AgentMessage);
+		return cleared as AgentMessage;
+	});
+
+	return { messages: next, tokensSaved: Math.max(0, tokensSaved), clearedCount: clearIdx.size };
+}
+
+interface ToolResultMessage {
+	role: "toolResult";
+	toolCallId: string;
+	toolName: string;
+	content: Array<{ type: string; text?: string }>;
+	isError: boolean;
+	timestamp: number;
+}
+
+function isAlreadyCleared(tr: ToolResultMessage): boolean {
+	return tr.content.length === 1 && tr.content[0].type === "text" && tr.content[0].text === CLEARED_TOOL_RESULT;
+}

src/compaction/types.ts

@@ -17,3 +17,11 @@ export interface CompactionResult {
 	messages: AgentMessage[];
 	details: CompactionDetails;
 }
+
+export interface MicrocompactResult {
+	messages: AgentMessage[];
+	/** Approximate tokens freed by clearing stale tool-result content. */
+	tokensSaved: number;
+	/** How many tool-result messages had their content cleared. */
+	clearedCount: number;
+}