@henryqw/pi-auto-compact 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# `@henryqw/pi-auto-compact`
+
+Pi extension that compacts context before it reaches 50% of current model context, then resumes current task.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-auto-compact
+```
+
+Restart Pi after installation. Remove with:
+
+```bash
+pi remove npm:@henryqw/pi-auto-compact
+```
+
+## Behavior
+
+- Checks `turn_start`, tool-call `turn_end`, `context`, and resumed/forked `session_start`.
+- Uses Pi's default `ctx.compact()` summary and session persistence.
+- Keeps newest 15% as temporary emergency context while compaction runs.
+- Sends a follow-up message after compaction so task execution continues.
+- Uses fixed 50% threshold; no configuration needed.
+
+`ctx.compact()` aborts current low-level run. Extension starts new run after compaction with the current task resume message.
+
+## Development
+
+```bash
+npm test
+npm run pack:check
+npm run test:live
+```
+
+`test:live` uses real Pi plus authenticated model access. It sets a temporary 12K context window, sends a large prompt, and verifies compaction, automatic resume, persisted resume message, and assistant response. Set `PI_AUTO_COMPACT_AUTH_FILE` when auth is not at `~/.pi/agent/auth.json`.

package/extensions/auto-compact.ts

@@ -0,0 +1,146 @@
+import { estimateTokens } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+type AgentMessage = Parameters<typeof estimateTokens>[0];
+
+/**
+ * Proactive compaction runs at three points:
+ * - turn_start: catch sessions already over threshold before next request.
+ * - turn_end: catch growth caused by tool results before next LLM turn.
+ * - context: last-resort guard with a temporary keep-recent context.
+ *
+ * Pi's ctx.compact() aborts active low-level run internally. Its completion
+ * callback sends follow-up user message, which resumes task after summary.
+ */
+const COMPACT_THRESHOLD_PERCENT = 50;
+
+// Emergency context guard keeps recent messages while default compaction runs.
+const KEEP_RECENT_PERCENT = 15;
+const RESUME_MESSAGE = "Auto-compact ran. Continue the current task.";
+
+/** Estimate current request size using same estimator Pi uses. */
+function estimateTotalTokens(messages: AgentMessage[]): number {
+	return messages.reduce((total, message) => total + estimateTokens(message), 0);
+}
+
+/**
+ * Do not cut inside assistant/toolResult history. A user boundary is safe:
+ * tool calls and their results belong to preceding turn.
+ */
+function snapToUserBoundary(messages: AgentMessage[], index: number): number {
+	while (index < messages.length && messages[index].role !== "user") index++;
+	return index;
+}
+
+/**
+ * Return temporary context containing newest messages plus notice.
+ * This changes only request context; session history remains intact.
+ */
+function keepRecent(messages: AgentMessage[], keepTokens: number): AgentMessage[] | null {
+	let tokens = 0;
+	let cutIndex = 0;
+
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const messageTokens = estimateTokens(messages[i]);
+		if (tokens + messageTokens > keepTokens) {
+			cutIndex = snapToUserBoundary(messages, i + 1);
+			break;
+		}
+		tokens += messageTokens;
+	}
+
+	if (cutIndex <= 0) return null;
+
+	const removed = messages.slice(0, cutIndex);
+	return [
+		{
+			role: "user",
+			content: `[Context compacted: ${removed.length} earlier messages (~${Math.round(estimateTotalTokens(removed) / 1000)}K tokens) were summarized. Continue with the current task.]`,
+			timestamp: Date.now(),
+		},
+		...messages.slice(cutIndex),
+	];
+}
+
+/** Final assistant turns need no automatic follow-up; tool turns do. */
+function hasToolCall(message: AgentMessage): boolean {
+	return (
+		message.role === "assistant" &&
+		Array.isArray(message.content) &&
+		message.content.some((part) => part.type === "toolCall")
+	);
+}
+
+export default function (pi: ExtensionAPI) {
+	// Prevent turn_start, turn_end, and context from starting duplicate summaries.
+	let compactionPending = false;
+
+	const runCompaction = (ctx: ExtensionContext) => {
+		ctx.compact({
+			onComplete: () => {
+				compactionPending = false;
+				// Pi may flush queued input during compaction_end. Wait one macrotask
+				// before checking idle, otherwise follow-up can race that flush.
+				setImmediate(() => {
+					if (ctx.isIdle()) pi.sendUserMessage(RESUME_MESSAGE);
+				});
+			},
+			onError: () => {
+				compactionPending = false;
+			},
+		});
+	};
+
+	const compactIfNeeded = (ctx: ExtensionContext) => {
+		if (compactionPending) return;
+
+		const usage = ctx.getContextUsage();
+		if (usage?.percent == null || usage.percent <= COMPACT_THRESHOLD_PERCENT) return;
+
+		compactionPending = true;
+		runCompaction(ctx);
+	};
+
+	// Do not use agent_settled here: long tool loops may cross threshold before
+	// the full run settles. These hooks inspect every provider-turn boundary.
+	// Pre-turn catches resumed/queued work before provider request starts.
+	pi.on("turn_start", (_event, ctx) => compactIfNeeded(ctx));
+
+	// Only tool-call turns need mid-run compaction. Final answers should not
+	// receive an unsolicited continuation message.
+	pi.on("turn_end", (event, ctx) => {
+		if (hasToolCall(event.message)) compactIfNeeded(ctx);
+	});
+
+	// Runs before every provider request. Temporary truncation protects request
+	// size while asynchronous default compaction summarizes persisted history.
+	pi.on("context", (event, ctx) => {
+		if (compactionPending) return;
+
+		const contextWindow = ctx.getContextUsage()?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+		const estimatedTokens = estimateTotalTokens(event.messages);
+		if (contextWindow <= 0 || estimatedTokens <= contextWindow * COMPACT_THRESHOLD_PERCENT / 100) return;
+
+		const truncated = keepRecent(
+			event.messages,
+			Math.floor(contextWindow * KEEP_RECENT_PERCENT / 100),
+		);
+		if (!truncated) return;
+
+		// Mark pending before deferring. Another context event can fire before
+		// setImmediate runs, and must not schedule a second compaction.
+		compactionPending = true;
+		setImmediate(() => runCompaction(ctx));
+		return { messages: truncated };
+	});
+
+	// Resume/fork can load an already-large session before first turn.
+	pi.on("session_start", (event, ctx) => {
+		if (event.reason === "resume" || event.reason === "fork") {
+			compactIfNeeded(ctx);
+		}
+	});
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@henryqw/pi-auto-compact",
+  "version": "0.1.0",
+  "description": "Proactively compact Pi context at 50% and resume the current task.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "compaction",
+    "context"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "test:live": "PI_AUTO_COMPACT_LIVE=1 node --test test/live.test.ts",
+    "typecheck": "tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/auto-compact.ts test/live.test.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-packages.git",
+    "directory": "packages/pi-auto-compact"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-packages/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ]
+  }
+}