@thunstack/auto-compact 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Dhiman
+
+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,116 @@
+# Pi Auto Compact
+
+Pi Auto Compact adds early, configurable context compaction to Pi and safely resumes unfinished tool-driven work after compaction.
+
+It uses Pi's native compaction API and summary format. It does not replace Pi's summarizer, rewrite session history, or make a second model call outside Pi's compaction flow.
+
+## What is missing in native Pi
+
+Pi already protects sessions from context overflow. Native automatic compaction runs when estimated context usage exceeds `contextWindow - reserveTokens`, and Pi lets users configure the response reserve and the amount of recent context to keep.
+
+That native behavior does not provide an early percentage trigger, a session-only toggle, an interactive settings panel, or an extension-managed continuation after compaction interrupts unfinished tool work. Pi Auto Compact fills those gaps while leaving native compaction available as a final safety net.
+
+| Capability | Native Pi | Pi Auto Compact |
+|---|---|---|
+| Automatic trigger | Near the model limit, based on reserved response tokens | At a configurable percentage of context usage |
+| Manual compaction | `/compact` | Unchanged |
+| Summary generation | Pi's native compaction prompt and session format | Uses the same native flow with optional supplemental guidance |
+| Session-only control | No dedicated toggle | `/auto-compact` |
+| Interactive configuration | Settings file | `/auto-compact-config` TUI panel |
+| Resume interrupted tool work | Native retry handles overflow recovery | Queues one configurable follow-up after successful early compaction |
+
+## Install
+
+```bash
+pi install npm:@thunstack/auto-compact
+```
+
+Try it for one Pi run without installing:
+
+```bash
+pi -e npm:@thunstack/auto-compact
+```
+
+Install directly from GitHub:
+
+```bash
+pi install git:github.com/aashishd/pi-auto-compact
+```
+
+Pi packages execute with your full system permissions. Review third-party extension source before installing it.
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `/auto-compact` | Toggle auto-compaction for the current session without changing the global startup default |
+| `/auto-compact-config` | Open the settings panel in Pi's interactive terminal UI |
+
+The settings command requires TUI mode. The compaction behavior itself also works in non-interactive modes.
+
+## Settings and defaults
+
+Global settings are stored in `$PI_CODING_AGENT_DIR/auto-compact.json`, or `~/.pi/agent/auto-compact.json` when that environment variable is unset. The file is created only after a setting is saved. Until then, in-memory defaults are used.
+
+| Setting | Default | Scope | Accepted values | Purpose |
+|---|---:|---|---|---|
+| `enabledAtSessionStart` | `true` | Global startup default | `true` or `false` | Sets whether new and forked sessions start with the extension active |
+| Active in current session | Startup default | Current session | `true` or `false` | Controlled by `/auto-compact`; restored on reload or resume and never written to global config |
+| `thresholdPercent` | `60` | Global | Integer `1` through `99` | Compacts only when context usage is strictly greater than this percentage |
+| `autoResume` | `true` | Global | `true` or `false` | Resumes only when compaction interrupted a non-terminating tool-driven turn |
+| `resumptionInstruction` | `Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step.` | Global | Any string | Follow-up user message queued once after successful interrupted compaction; blank disables the follow-up |
+| `waitForTurnEnd` | `true` | Fixed safety setting | `true` only | Defers compaction to Pi's `turn_end` boundary; `false` is rejected because Pi does not expose a safe reliable live boundary |
+| `additionalCompactionInstruction` | `Preserve unfinished work and exact details required to resume safely.` | Global | Any string | Appends guidance to Pi's native compaction prompt; blank uses only the native prompt |
+
+Equivalent config file:
+
+```json
+{
+  "version": 1,
+  "enabledAtSessionStart": true,
+  "thresholdPercent": 60,
+  "autoResume": true,
+  "resumptionInstruction": "Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step.",
+  "waitForTurnEnd": true,
+  "additionalCompactionInstruction": "Preserve unfinished work and exact details required to resume safely."
+}
+```
+
+Use `/auto-compact-config` instead of editing the file when TUI mode is available. Saves are written atomically with owner-only permissions.
+
+## How it behaves
+
+1. After each completed Pi turn, the extension reads the active model's context usage.
+2. When usage crosses above the configured threshold, it requests Pi's native compaction flow.
+3. The detector disarms until usage returns to or below the threshold, preventing repeated compactions at the same usage level.
+4. If that compaction interrupted a non-terminating tool-driven turn, the extension queues the resumption instruction exactly once.
+5. Session replacement or reload invalidates stale completion callbacks, so old compactions cannot resume a new runtime.
+
+A tool result that explicitly requests termination is respected, including mixed tool batches. Final assistant responses are never auto-resumed.
+
+### Interaction with native auto-compaction
+
+This extension does not disable Pi's built-in threshold or overflow recovery. With the default 60% trigger, it normally compacts before Pi reaches its native reserve boundary. If native compaction runs first, Pi handles that event normally and this extension does not add its auto-resume message.
+
+Pi's native compaction settings still control how much recent context is kept and how much response space is reserved.
+
+## Uninstall
+
+```bash
+pi remove npm:@thunstack/auto-compact
+```
+
+Removing the package does not delete `~/.pi/agent/auto-compact.json`. Delete that optional settings file separately if you no longer want it.
+
+## Development
+
+```bash
+npm install
+npm run check
+```
+
+`npm run check` type-checks the extension, runs the behavior tests, and previews the npm tarball. Publishing also runs the same checks through `prepublishOnly`.
+
+## License
+
+MIT

package/extensions/auto-compact/index.ts

@@ -0,0 +1,786 @@
+import {
+	closeSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import type {
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionContext,
+	ExtensionEvent,
+	SessionStartEvent,
+	Theme,
+	TurnEndEvent,
+} from "@earendil-works/pi-coding-agent";
+import {
+	Container,
+	Input,
+	SettingsList,
+	Text,
+	type Component,
+	type Focusable,
+	type SettingItem,
+	type SettingsListTheme,
+} from "@earendil-works/pi-tui";
+
+type ToolExecutionEndEvent = Extract<
+	ExtensionEvent,
+	{ type: "tool_execution_end" }
+>;
+
+export const AUTO_COMPACT_CONFIG_VERSION = 1;
+export const AUTO_COMPACT_SESSION_ENTRY = "auto-compact-state";
+
+export interface AutoCompactConfig {
+	version: 1;
+	enabledAtSessionStart: boolean;
+	thresholdPercent: number;
+	autoResume: boolean;
+	resumptionInstruction: string;
+	waitForTurnEnd: true;
+	additionalCompactionInstruction: string;
+}
+
+interface AutoCompactSessionState {
+	version: 1;
+	isActive: boolean;
+}
+
+export const DEFAULT_AUTO_COMPACT_CONFIG: Readonly<AutoCompactConfig> = {
+	version: AUTO_COMPACT_CONFIG_VERSION,
+	enabledAtSessionStart: true,
+	thresholdPercent: 60,
+	autoResume: true,
+	resumptionInstruction:
+		"Continue the unfinished work from the compaction summary. Preserve prior decisions, avoid repeating completed work, and proceed with the next pending step.",
+	waitForTurnEnd: true,
+	additionalCompactionInstruction:
+		"Preserve unfinished work and exact details required to resume safely.",
+};
+
+function defaultConfig(): AutoCompactConfig {
+	return { ...DEFAULT_AUTO_COMPACT_CONFIG };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeAutoCompactConfig(value: unknown): AutoCompactConfig {
+	if (!isRecord(value)) return defaultConfig();
+	if (
+		Object.prototype.hasOwnProperty.call(value, "version") &&
+		value.version !== AUTO_COMPACT_CONFIG_VERSION
+	) {
+		return defaultConfig();
+	}
+	return {
+		version: AUTO_COMPACT_CONFIG_VERSION,
+		enabledAtSessionStart:
+			typeof value.enabledAtSessionStart === "boolean"
+				? value.enabledAtSessionStart
+				: DEFAULT_AUTO_COMPACT_CONFIG.enabledAtSessionStart,
+		thresholdPercent:
+			Number.isInteger(value.thresholdPercent) &&
+			typeof value.thresholdPercent === "number" &&
+			value.thresholdPercent >= 1 &&
+			value.thresholdPercent <= 99
+				? value.thresholdPercent
+				: DEFAULT_AUTO_COMPACT_CONFIG.thresholdPercent,
+		autoResume:
+			typeof value.autoResume === "boolean"
+				? value.autoResume
+				: DEFAULT_AUTO_COMPACT_CONFIG.autoResume,
+		resumptionInstruction:
+			typeof value.resumptionInstruction === "string"
+				? value.resumptionInstruction
+				: DEFAULT_AUTO_COMPACT_CONFIG.resumptionInstruction,
+		waitForTurnEnd: true,
+		additionalCompactionInstruction:
+			typeof value.additionalCompactionInstruction === "string"
+				? value.additionalCompactionInstruction
+				: DEFAULT_AUTO_COMPACT_CONFIG.additionalCompactionInstruction,
+	};
+}
+
+export function getAutoCompactConfigPath(): string {
+	const agentDirectory =
+		process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+	return join(agentDirectory, "auto-compact.json");
+}
+
+export function readAutoCompactConfig(path = getAutoCompactConfigPath()): AutoCompactConfig {
+	try {
+		return normalizeAutoCompactConfig(JSON.parse(readFileSync(path, "utf8")));
+	} catch {
+		return defaultConfig();
+	}
+}
+
+export type RenameConfigFile = (temporaryPath: string, targetPath: string) => void;
+
+export function writeAutoCompactConfig(
+	path: string,
+	config: AutoCompactConfig,
+	renameFile: RenameConfigFile = renameSync,
+): void {
+	const directory = dirname(path);
+	mkdirSync(directory, { recursive: true });
+	const temporaryPath = join(
+		directory,
+		`.${basename(path)}.${process.pid}.${randomUUID()}.tmp`,
+	);
+	let descriptor: number | undefined;
+	try {
+		descriptor = openSync(temporaryPath, "wx", 0o600);
+		writeFileSync(
+			descriptor,
+			`${JSON.stringify(normalizeAutoCompactConfig(config), null, 2)}\n`,
+			"utf8",
+		);
+		fsyncSync(descriptor);
+		closeSync(descriptor);
+		descriptor = undefined;
+		renameFile(temporaryPath, path);
+	} catch (error) {
+		if (descriptor !== undefined) {
+			try {
+				closeSync(descriptor);
+			} catch {
+				// Preserve the original write error.
+			}
+		}
+		try {
+			unlinkSync(temporaryPath);
+		} catch {
+			// The temporary file may not have been created or may already be renamed.
+		}
+		throw error;
+	}
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function notify(
+	ctx: ExtensionContext,
+	message: string,
+	level: "info" | "warning" | "error",
+): void {
+	if (ctx.hasUI) ctx.ui.notify(message, level);
+}
+
+function validPercent(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+function restoreSessionActivation(ctx: ExtensionContext): boolean | undefined {
+	let restored: boolean | undefined;
+	for (const entry of ctx.sessionManager.getEntries()) {
+		if (entry.type !== "custom" || entry.customType !== AUTO_COMPACT_SESSION_ENTRY) {
+			continue;
+		}
+		const state = entry.data as Partial<AutoCompactSessionState> | undefined;
+		if (typeof state?.isActive === "boolean") restored = state.isActive;
+	}
+	return restored;
+}
+
+function toolCallIds(event: TurnEndEvent): string[] {
+	if (event.message.role !== "assistant") return [];
+	const ids: string[] = [];
+	for (const content of event.message.content) {
+		if (content.type === "toolCall") ids.push(content.id);
+	}
+	return ids;
+}
+
+export function isInterruptedToolTurn(
+	event: TurnEndEvent,
+	terminatedToolCalls: ReadonlySet<string>,
+): boolean {
+	const ids = toolCallIds(event);
+	return ids.length > 0 && !ids.some((id) => terminatedToolCalls.has(id));
+}
+
+export type PersistAutoCompactConfig = (
+	path: string,
+	config: AutoCompactConfig,
+) => void;
+
+export class AutoCompactRuntime {
+	private config: AutoCompactConfig;
+	private isActive: boolean;
+	private detectorArmed = true;
+	private inFlightToken: symbol | undefined;
+	private generation = 0;
+	private readonly terminatedToolCalls = new Set<string>();
+
+	constructor(
+		private readonly pi: ExtensionAPI,
+		private readonly configPath: string,
+		initialConfig: AutoCompactConfig,
+		private readonly persistConfig: PersistAutoCompactConfig = writeAutoCompactConfig,
+	) {
+		this.config = normalizeAutoCompactConfig(initialConfig);
+		this.isActive = this.config.enabledAtSessionStart;
+	}
+
+	getConfig(): AutoCompactConfig {
+		return { ...this.config };
+	}
+
+	getIsActive(): boolean {
+		return this.isActive;
+	}
+
+	getDetectorState(): { armed: boolean; inFlight: boolean; generation: number } {
+		return {
+			armed: this.detectorArmed,
+			inFlight: this.inFlightToken !== undefined,
+			generation: this.generation,
+		};
+	}
+
+	setSessionActive(active: boolean): void {
+		this.isActive = active;
+		this.pi.appendEntry<AutoCompactSessionState>(AUTO_COMPACT_SESSION_ENTRY, {
+			version: AUTO_COMPACT_CONFIG_VERSION,
+			isActive: active,
+		});
+	}
+
+	updateGlobalConfig(config: AutoCompactConfig, ctx: ExtensionContext): boolean {
+		const candidate = normalizeAutoCompactConfig(config);
+		try {
+			this.persistConfig(this.configPath, candidate);
+		} catch (error) {
+			notify(
+				ctx,
+				`Auto-compact config was not saved: ${errorMessage(error)}`,
+				"error",
+			);
+			return false;
+		}
+		this.config = candidate;
+		return true;
+	}
+
+	setWaitForTurnEnd(wait: boolean, ctx: ExtensionContext): boolean {
+		if (!wait) {
+			notify(
+				ctx,
+				"Wait for turn end must remain yes. Pi lacks a safe reliable live boundary, so eager compaction is deferred.",
+				"warning",
+			);
+			return false;
+		}
+		return true;
+	}
+
+	resetDefaults(ctx: ExtensionContext): boolean {
+		if (!this.updateGlobalConfig(defaultConfig(), ctx)) return false;
+		this.setSessionActive(DEFAULT_AUTO_COMPACT_CONFIG.enabledAtSessionStart);
+		return true;
+	}
+
+	onSessionStart(event: SessionStartEvent, ctx: ExtensionContext): void {
+		this.generation++;
+		this.inFlightToken = undefined;
+		this.detectorArmed = true;
+		this.terminatedToolCalls.clear();
+
+		const mustUseStartupDefault = event.reason === "new" || event.reason === "fork";
+		const restored = mustUseStartupDefault ? undefined : restoreSessionActivation(ctx);
+		this.isActive = restored ?? this.config.enabledAtSessionStart;
+		if (mustUseStartupDefault || restored === undefined) {
+			this.pi.appendEntry<AutoCompactSessionState>(AUTO_COMPACT_SESSION_ENTRY, {
+				version: AUTO_COMPACT_CONFIG_VERSION,
+				isActive: this.isActive,
+			});
+		}
+	}
+
+	onSessionShutdown(): void {
+		this.generation++;
+		this.inFlightToken = undefined;
+		this.terminatedToolCalls.clear();
+	}
+
+	onToolExecutionEnd(event: ToolExecutionEndEvent): void {
+		if (isRecord(event.result) && event.result.terminate === true) {
+			this.terminatedToolCalls.add(event.toolCallId);
+		} else {
+			this.terminatedToolCalls.delete(event.toolCallId);
+		}
+	}
+
+	onTurnEnd(event: TurnEndEvent, ctx: ExtensionContext): void {
+		const interrupted = isInterruptedToolTurn(event, this.terminatedToolCalls);
+		this.terminatedToolCalls.clear();
+
+		const percent = ctx.getContextUsage()?.percent;
+		if (!validPercent(percent)) return;
+		if (percent <= this.config.thresholdPercent) {
+			this.detectorArmed = true;
+			return;
+		}
+		if (!this.isActive || !this.detectorArmed || this.inFlightToken !== undefined) {
+			return;
+		}
+
+		this.detectorArmed = false;
+		const token = Symbol("auto-compact");
+		const callbackGeneration = this.generation;
+		this.inFlightToken = token;
+		const additionalInstruction = this.config.additionalCompactionInstruction;
+		const customInstructions = additionalInstruction.trim()
+			? additionalInstruction
+			: undefined;
+		notify(
+			ctx,
+			`Auto-compacting at ${percent.toFixed(1)}% context usage.`,
+			"info",
+		);
+
+		const settle = (error?: Error) => {
+			if (
+				callbackGeneration !== this.generation ||
+				this.inFlightToken !== token
+			) {
+				return;
+			}
+			this.inFlightToken = undefined;
+			if (error) {
+				this.detectorArmed = true;
+				notify(ctx, `Auto-compaction failed: ${error.message}`, "error");
+				return;
+			}
+
+			notify(ctx, "Auto-compaction completed.", "info");
+			if (!interrupted || !this.isActive || !this.config.autoResume) return;
+			const instruction = this.config.resumptionInstruction;
+			if (!instruction.trim()) return;
+			try {
+				this.pi.sendUserMessage(instruction, { deliverAs: "followUp" });
+			} catch (resumeError) {
+				notify(
+					ctx,
+					`Auto-compact could not resume: ${errorMessage(resumeError)}`,
+					"error",
+				);
+			}
+		};
+
+		try {
+			ctx.compact({
+				customInstructions,
+				onComplete: () => settle(),
+				onError: (error) => settle(error),
+			});
+		} catch (error) {
+			settle(error instanceof Error ? error : new Error(String(error)));
+		}
+	}
+}
+
+type AutoCompactSettingId =
+	| "enabledAtSessionStart"
+	| "isActive"
+	| "thresholdPercent"
+	| "autoResume"
+	| "resumptionInstruction"
+	| "waitForTurnEnd"
+	| "additionalCompactionInstruction"
+	| "resetDefaults"
+	| "close";
+
+function yesNo(value: boolean): string {
+	return value ? "yes" : "no";
+}
+
+function settingsListTheme(theme: Theme): SettingsListTheme {
+	return {
+		label: (text, selected) =>
+			selected ? theme.fg("accent", theme.bold(text)) : text,
+		value: (text, selected) =>
+			selected ? theme.fg("accent", text) : theme.fg("dim", text),
+		description: (text) => theme.fg("dim", text),
+		cursor: theme.fg("accent", "›"),
+		hint: (text) => theme.fg("dim", text),
+	};
+}
+
+function valueInput(
+	title: string,
+	currentValue: string,
+	theme: Theme,
+	done: (selectedValue?: string) => void,
+): Component & Focusable {
+	const input = new Input();
+	input.onSubmit = (value) => done(value);
+	input.onEscape = () => done(undefined);
+	return {
+		get focused() {
+			return input.focused;
+		},
+		set focused(value: boolean) {
+			input.focused = value;
+		},
+		render: (width: number) => [
+			theme.fg("accent", theme.bold(title)),
+			theme.fg("dim", `Current: ${currentValue || "(empty)"}`),
+			theme.fg("dim", "type replacement • enter save • esc back"),
+			...input.render(width),
+		],
+		invalidate: () => input.invalidate(),
+		handleInput: (data: string) => input.handleInput(data),
+	};
+}
+
+function resetConfirmation(
+	theme: Theme,
+	done: (selectedValue?: string) => void,
+): Component {
+	const container = new Container();
+	container.addChild(
+		new Text(theme.fg("warning", theme.bold("Reset auto-compact defaults?")), 1, 1),
+	);
+	const list = new SettingsList(
+		[
+			{
+				id: "confirm",
+				label: "Confirm reset",
+				currentValue: "no",
+				values: ["no", "yes"],
+				description:
+					"Resets every machine-global value and activates auto-compact in this session.",
+			},
+			{
+				id: "cancel",
+				label: "Cancel",
+				currentValue: "back",
+				values: ["back"],
+			},
+		],
+		4,
+		settingsListTheme(theme),
+		(id, value) => {
+			if (id === "confirm" && value === "yes") done("confirmed");
+			if (id === "cancel") done(undefined);
+		},
+		() => done(undefined),
+	);
+	container.addChild(list);
+	return {
+		render: (width: number) => container.render(width),
+		invalidate: () => container.invalidate(),
+		handleInput: (data: string) => list.handleInput(data),
+	};
+}
+
+function settingsItems(
+	runtime: AutoCompactRuntime,
+	theme: Theme,
+): SettingItem[] {
+	const config = runtime.getConfig();
+	return [
+		{
+			id: "enabledAtSessionStart",
+			label: "Enabled at session start",
+			currentValue: yesNo(config.enabledAtSessionStart),
+			values: ["yes", "no"],
+			description:
+				"Machine-global startup default. Changes affect future sessions only.",
+		},
+		{
+			id: "isActive",
+			label: "Active in current session",
+			currentValue: yesNo(runtime.getIsActive()),
+			values: ["yes", "no"],
+			description:
+				"New and forked sessions initialize from Enabled at session start; reload/resume of this session restores its stored state.",
+		},
+		{
+			id: "thresholdPercent",
+			label: "Threshold",
+			currentValue: `${config.thresholdPercent}%`,
+			description: "Integer context percentage from 1 through 99.",
+			submenu: (_currentValue, done) =>
+				valueInput(
+					"Threshold percent (1..99)",
+					String(runtime.getConfig().thresholdPercent),
+					theme,
+					done,
+				),
+		},
+		{
+			id: "autoResume",
+			label: "Auto-resume",
+			currentValue: yesNo(config.autoResume),
+			values: ["yes", "no"],
+			description: "Resume only when auto-compaction interrupted a tool-driven turn.",
+		},
+		{
+			id: "resumptionInstruction",
+			label: "Resumption instruction",
+			currentValue: config.resumptionInstruction || "(empty)",
+			description: "User message queued once after successful interrupted compaction.",
+			submenu: (_currentValue, done) =>
+				valueInput(
+					"Resumption instruction",
+					runtime.getConfig().resumptionInstruction,
+					theme,
+					done,
+				),
+		},
+		{
+			id: "waitForTurnEnd",
+			label: "Wait for turn end",
+			currentValue: "yes",
+			values: ["yes", "no"],
+			description:
+				"Safe-only in this version. No is deferred because Pi lacks a safe reliable live boundary.",
+		},
+		{
+			id: "additionalCompactionInstruction",
+			label: "Additional compaction instruction",
+			currentValue: config.additionalCompactionInstruction || "(native prompt only)",
+			description:
+				"Pi's native /compact instruction is always used. This text is appended only as additional guidance and never edits or replaces the native instruction. " +
+				"Changing it may affect compaction quality. Empty means native prompt only.",
+			submenu: (_currentValue, done) =>
+				valueInput(
+					"Additional compaction instruction",
+					runtime.getConfig().additionalCompactionInstruction,
+					theme,
+					done,
+				),
+		},
+		{
+			id: "resetDefaults",
+			label: "Reset defaults",
+			currentValue: "open",
+			description: "Requires confirmation before resetting global and session values.",
+			submenu: (_currentValue, done) => resetConfirmation(theme, done),
+		},
+		{
+			id: "close",
+			label: "Close",
+			currentValue: "close",
+			values: ["close"],
+		},
+	];
+}
+
+async function openAutoCompactSettings(
+	ctx: ExtensionCommandContext,
+	runtime: AutoCompactRuntime,
+): Promise<void> {
+	await ctx.ui.custom(
+		(tui, theme, _keybindings, done) => {
+			const container = new Container();
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold("Auto-compact Settings")), 1, 1),
+			);
+			let settingsList: SettingsList;
+			const refresh = () => {
+				for (const item of settingsItems(runtime, theme)) {
+					settingsList.updateValue(item.id, item.currentValue);
+				}
+				tui.requestRender();
+			};
+			const saveGlobal = (
+				patch: Partial<Omit<AutoCompactConfig, "version" | "waitForTurnEnd">>,
+				message: string,
+			) => {
+				const saved = runtime.updateGlobalConfig(
+					{ ...runtime.getConfig(), ...patch },
+					ctx,
+				);
+				if (saved) notify(ctx, message, "info");
+				refresh();
+			};
+
+			settingsList = new SettingsList(
+				settingsItems(runtime, theme),
+				10,
+				settingsListTheme(theme),
+				(id, newValue) => {
+					const action = id as AutoCompactSettingId;
+					switch (action) {
+						case "enabledAtSessionStart":
+							saveGlobal(
+								{ enabledAtSessionStart: newValue === "yes" },
+								"Auto-compact startup default updated for future sessions.",
+							);
+							return;
+						case "isActive":
+							runtime.setSessionActive(newValue === "yes");
+							notify(
+								ctx,
+								`Auto-compact ${newValue === "yes" ? "enabled" : "disabled"} for this session.`,
+								"info",
+							);
+							refresh();
+							return;
+						case "thresholdPercent": {
+							const threshold = Number(newValue);
+							if (
+								!Number.isInteger(threshold) ||
+								threshold < 1 ||
+								threshold > 99
+							) {
+								notify(
+									ctx,
+									"Threshold must be an integer from 1 through 99.",
+									"warning",
+								);
+								refresh();
+								return;
+							}
+							saveGlobal(
+								{ thresholdPercent: threshold },
+								`Auto-compact threshold set to ${threshold}%.`,
+							);
+							return;
+						}
+						case "autoResume":
+							saveGlobal(
+								{ autoResume: newValue === "yes" },
+								`Auto-resume ${newValue === "yes" ? "enabled" : "disabled"}.`,
+							);
+							return;
+						case "resumptionInstruction":
+							saveGlobal(
+								{ resumptionInstruction: newValue },
+								"Auto-compact resumption instruction updated.",
+							);
+							return;
+						case "waitForTurnEnd":
+							runtime.setWaitForTurnEnd(newValue === "yes", ctx);
+							refresh();
+							return;
+						case "additionalCompactionInstruction":
+							saveGlobal(
+								{ additionalCompactionInstruction: newValue },
+								"Additional compaction guidance updated.",
+							);
+							return;
+						case "resetDefaults":
+							if (newValue === "confirmed" && runtime.resetDefaults(ctx)) {
+								notify(
+									ctx,
+									"Auto-compact defaults restored and enabled for this session.",
+									"info",
+								);
+							}
+							refresh();
+							return;
+						case "close":
+							done(undefined);
+					}
+				},
+				() => done(undefined),
+			);
+			container.addChild(settingsList);
+			container.addChild(
+				new Text(
+					theme.fg("dim", "j/k scroll • enter edit/save • esc close"),
+					1,
+					0,
+				),
+			);
+			return {
+				render: (width: number) => container.render(width),
+				invalidate: () => container.invalidate(),
+				handleInput: (data: string) => {
+					settingsList.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				anchor: "bottom-left",
+				width: 92,
+				maxHeight: "85%",
+				margin: { bottom: 1 },
+			},
+		},
+	);
+}
+
+export interface AutoCompactExtensionOptions {
+	configPath?: string;
+	initialConfig?: AutoCompactConfig;
+	persistConfig?: PersistAutoCompactConfig;
+	onRuntime?: (runtime: AutoCompactRuntime) => void;
+}
+
+export function registerAutoCompactExtension(
+	pi: ExtensionAPI,
+	options: AutoCompactExtensionOptions = {},
+): AutoCompactRuntime {
+	const configPath = options.configPath ?? getAutoCompactConfigPath();
+	const runtime = new AutoCompactRuntime(
+		pi,
+		configPath,
+		options.initialConfig ?? readAutoCompactConfig(configPath),
+		options.persistConfig,
+	);
+	options.onRuntime?.(runtime);
+
+	pi.registerCommand("auto-compact", {
+		description: "Toggle auto-compaction for the current session",
+		handler: async (_args, ctx) => {
+			const active = !runtime.getIsActive();
+			runtime.setSessionActive(active);
+			notify(
+				ctx,
+				`Auto-compact ${active ? "enabled" : "disabled"} for this session.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("auto-compact-config", {
+		description: "Configure auto-compaction",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI || ctx.mode !== "tui") {
+				notify(ctx, "/auto-compact-config requires TUI mode.", "warning");
+				return;
+			}
+			try {
+				await openAutoCompactSettings(ctx, runtime);
+			} catch (error) {
+				notify(
+					ctx,
+					`Could not open auto-compact settings: ${errorMessage(error)}`,
+					"error",
+				);
+			}
+		},
+	});
+
+	pi.on("session_start", (event, ctx) => runtime.onSessionStart(event, ctx));
+	pi.on("session_shutdown", () => runtime.onSessionShutdown());
+	pi.on("tool_execution_end", (event) => runtime.onToolExecutionEnd(event));
+	pi.on("turn_end", (event, ctx) => runtime.onTurnEnd(event, ctx));
+
+	return runtime;
+}
+
+export default function autoCompactExtension(pi: ExtensionAPI): void {
+	registerAutoCompactExtension(pi);
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@thunstack/auto-compact",
+  "version": "0.1.0",
+  "description": "Early, configurable context auto-compaction for Pi with safe tool-turn resumption.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "auto-compact",
+    "compaction",
+    "context-window",
+    "context-management",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "author": "Ashish Dhiman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aashishd/pi-auto-compact.git"
+  },
+  "homepage": "https://github.com/aashishd/pi-auto-compact#readme",
+  "bugs": {
+    "url": "https://github.com/aashishd/pi-auto-compact/issues"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/auto-compact/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.7",
+    "@earendil-works/pi-tui": "0.80.7",
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "test": "tsx --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "pack:dry-run": "npm pack --dry-run",
+    "check": "npm run typecheck && npm test && npm run pack:dry-run",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}