@lll9p/pi-better-compaction 0.4.0 → 0.6.0

package/README.md

@@ -44,6 +44,10 @@ If the file doesn't exist, all defaults apply. The extension never creates this
 ```jsonc
 {
   "enabled": true,
+  "midRun": {
+    "enabled": false,
+    "thresholdPercent": 80
+  },
   "compactionVersion": "v2",
   "compactionModel": null,
   "compactionThinkingLevel": "off",
@@ -65,6 +69,8 @@ If the file doesn't exist, all defaults apply. The extension never creates this
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `enabled` | `boolean` | `true` | Master switch. Set `false` to disable the extension entirely. |
+| `midRun.enabled` | `boolean` | `false` | Reserved and currently ignored. The mid-run guard remains disabled even when set to `true`. |
+| `midRun.thresholdPercent` | `number` | `80` | Reserved threshold for the disabled mid-run guard. Must be greater than 0 and at most 100. |
 | `compactionVersion` | `"v1" \| "v2"` | `"v2"` | Protocol for Responses-family APIs. **V2** (streaming, encrypted blob) is the current OpenAI default. **V1** uses the legacy `/responses/compact` endpoint. |
 | `compactionModel` | `string \| null` | `null` | Model for fallback compaction (non-Responses APIs, or when native compact fails). Format: `"provider/model-id"`, e.g. `"openai/gpt-5.1-mini"`. `null` = let pi use the current chat model. |
 | `compactionThinkingLevel` | `string` | `"off"` | Thinking level for the fallback compaction model. One of: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. |

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-一个 [pi](https://github.com/nicepkg/pi) 扩展，通过两条策略提升上下文压缩效果：
+一个 [pi](https://github.com/nicepkg/pi) 扩展，通过两条协同策略提升上下文压缩效果：
 
 1. **OpenAI Responses 系列 API** 使用提供商原生压缩端点，保留纯文本摘要无法留存的不透明上下文。
 2. **其他所有 API**（Anthropic、Gemini 等）可用一个**独立的低成本模型**执行 pi 内置压缩，避免在主模型上消耗额度。
@@ -44,6 +44,10 @@ cd pi-better-compaction && pi install .
 ```jsonc
 {
   "enabled": true,
+  "midRun": {
+    "enabled": false,
+    "thresholdPercent": 80
+  },
   "compactionVersion": "v2",
   "compactionModel": null,
   "compactionThinkingLevel": "off",
@@ -65,6 +69,8 @@ cd pi-better-compaction && pi install .
 | 选项 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `enabled` | `boolean` | `true` | 总开关。设为 `false` 完全禁用扩展。 |
+| `midRun.enabled` | `boolean` | `false` | 保留配置，当前会被忽略。即使设为 `true`，mid-run guard 仍保持禁用。 |
+| `midRun.thresholdPercent` | `number` | `80` | 已禁用的 mid-run guard 的保留阈值。必须大于 0 且不超过 100。 |
 | `compactionVersion` | `"v1" \| "v2"` | `"v2"` | Responses 系列 API 的压缩协议。**V2**（流式，加密 blob）是 OpenAI 当前默认协议；**V1** 使用旧版 `/responses/compact` 端点。 |
 | `compactionModel` | `string \| null` | `null` | 回退压缩使用的模型（用于非 Responses API，或原生压缩失败时）。格式：`"provider/model-id"`，如 `"openai/gpt-5.1-mini"`。`null` = 由 pi 使用当前对话模型。 |
 | `compactionThinkingLevel` | `string` | `"off"` | 回退压缩模型的思考级别。可选：`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`。 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lll9p/pi-better-compaction",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Better compaction for pi: native /responses/compact replay for OpenAI Responses APIs, plus a configurable compaction model driving pi's native summarization everywhere else.",
   "author": "Lilin Lao",
@@ -38,6 +38,7 @@
     "src/debug.ts",
     "src/details-store.ts",
     "src/extension-runtime.ts",
+    "src/midrun.ts",
     "src/native-fallback.ts",
     "src/payload-rewrite.ts",
     "src/request-context-cache.ts",

package/src/config.ts

@@ -60,6 +60,15 @@ function toBoolean(value: unknown, fieldPath: string, warnings: string[]): boole
 	return undefined;
 }
 
+function toThresholdPercent(value: unknown, fieldPath: string, warnings: string[]): number | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value === "number" && Number.isFinite(value) && value > 0 && value <= 100) {
+		return value;
+	}
+	warnings.push(`Ignoring ${fieldPath}: expected a number greater than 0 and at most 100.`);
+	return undefined;
+}
+
 function toModelSpec(value: unknown, fieldPath: string, warnings: string[]): string | null | undefined {
 	if (value === undefined) return undefined;
 	// Explicit null clears a spec, matching the documented "unset = current model" behavior.
@@ -119,6 +128,7 @@ export function loadExtensionConfig(configPath: string = CONFIG_PATH): LoadedExt
 	const warnings: string[] = [];
 	const resolved: ExtensionConfig = {
 		...DEFAULT_EXTENSION_CONFIG,
+		midRun: { ...DEFAULT_EXTENSION_CONFIG.midRun },
 		responsesCompactApis: [...DEFAULT_EXTENSION_CONFIG.responsesCompactApis],
 	};
 	let source: string | undefined;
@@ -128,6 +138,19 @@ export function loadExtensionConfig(configPath: string = CONFIG_PATH): LoadedExt
 		source = configPath;
 
 		resolved.enabled = toBoolean(raw.enabled, "enabled", warnings) ?? resolved.enabled;
+
+		if (raw.midRun === undefined) {
+			// Keep defaults.
+		} else if (isRecord(raw.midRun)) {
+			resolved.midRun.enabled =
+				toBoolean(raw.midRun.enabled, "midRun.enabled", warnings) ?? resolved.midRun.enabled;
+			resolved.midRun.thresholdPercent =
+				toThresholdPercent(raw.midRun.thresholdPercent, "midRun.thresholdPercent", warnings) ??
+				resolved.midRun.thresholdPercent;
+		} else {
+			warnings.push("Ignoring midRun: expected a JSON object.");
+		}
+
 		resolved.allowCompactionContinuityBreak =
 			toBoolean(raw.allowCompactionContinuityBreak, "allowCompactionContinuityBreak", warnings) ??
 			resolved.allowCompactionContinuityBreak;

package/src/extension-runtime.ts

@@ -40,6 +40,20 @@ type ResponsesCompactOutcome =
 	| { outcome: "aborted" }
 	| { outcome: "failed" };
 
+export type ExtensionRuntimeDependencies = {
+	loadExtensionConfig: typeof loadExtensionConfig;
+	executeNativeCompaction: typeof executeNativeCompaction;
+	executeV2Compaction: typeof executeV2Compaction;
+	runNativeFallbackCompaction: typeof runNativeFallbackCompaction;
+};
+
+const DEFAULT_DEPENDENCIES: ExtensionRuntimeDependencies = {
+	loadExtensionConfig,
+	executeNativeCompaction,
+	executeV2Compaction,
+	runNativeFallbackCompaction,
+};
+
 function buildCompactionRequestMeta(event: SessionBeforeCompactEvent): NativeCompactionRequestMeta {
 	return {
 		tokensBefore: event.preparation.tokensBefore,
@@ -91,7 +105,7 @@ function buildCompactionInstructions(systemPrompt: string, customInstructions?:
 		return systemPrompt;
 	}
 
-	return `${systemPrompt}\n\nAdditional user guidance for this manual /compact request:\n${guidance}`;
+	return `${systemPrompt}\n\nAdditional compaction guidance:\n${guidance}`;
 }
 
 async function runResponsesV1Compact(
@@ -99,6 +113,7 @@ async function runResponsesV1Compact(
 	ctx: ExtensionContext,
 	config: ExtensionConfig,
 	runtime: NativeCompactionRuntime,
+	dependencies: ExtensionRuntimeDependencies,
 ): Promise<ResponsesCompactOutcome> {
 	const instructions = buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions);
 	const branchEntries = ctx.sessionManager.getBranch();
@@ -161,7 +176,7 @@ async function runResponsesV1Compact(
 		request = { ...request, ...extras };
 	}
 
-	const compactResult = await executeNativeCompaction({
+	const compactResult = await dependencies.executeNativeCompaction({
 		runtime,
 		request,
 		signal: event.signal,
@@ -251,6 +266,7 @@ async function runResponsesV2Compact(
 	ctx: ExtensionContext,
 	config: ExtensionConfig,
 	runtime: NativeCompactionRuntime,
+	dependencies: ExtensionRuntimeDependencies,
 ): Promise<ResponsesCompactOutcome> {
 	const instructions = buildCompactionInstructions(ctx.getSystemPrompt(), event.customInstructions);
 	const branchEntries = ctx.sessionManager.getBranch();
@@ -311,7 +327,7 @@ async function runResponsesV2Compact(
 		request = { ...request, ...extras };
 	}
 
-	const v2Result = await executeV2Compaction({
+	const v2Result = await dependencies.executeV2Compaction({
 		runtime,
 		request,
 		signal: event.signal,
@@ -400,8 +416,12 @@ async function runResponsesV2Compact(
 	return { outcome: "success", compaction };
 }
 
-async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx: ExtensionContext) {
-	const { config } = loadExtensionConfig();
+async function handleSessionBeforeCompact(
+	event: SessionBeforeCompactEvent,
+	ctx: ExtensionContext,
+	dependencies: ExtensionRuntimeDependencies,
+) {
+	const { config } = dependencies.loadExtensionConfig();
 	if (!config.enabled) {
 		return undefined;
 	}
@@ -436,9 +456,9 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 		let responsesOutcome: ResponsesCompactOutcome;
 
 		if (config.compactionVersion === "v2") {
-			responsesOutcome = await runResponsesV2Compact(event, ctx, config, resolution.runtime);
+			responsesOutcome = await runResponsesV2Compact(event, ctx, config, resolution.runtime, dependencies);
 		} else {
-			responsesOutcome = await runResponsesV1Compact(event, ctx, config, resolution.runtime);
+			responsesOutcome = await runResponsesV1Compact(event, ctx, config, resolution.runtime, dependencies);
 		}
 
 		if (responsesOutcome.outcome === "success") {
@@ -465,7 +485,12 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 	}
 
 	// Branch 2: run pi's native compaction method with the configured model.
-	const fallback = await runNativeFallbackCompaction({ ctx, event, config, sessionId: getSessionId(ctx) });
+	const fallback = await dependencies.runNativeFallbackCompaction({
+		ctx,
+		event,
+		config,
+		sessionId: getSessionId(ctx),
+	});
 	if (fallback.ok) {
 		if (ctx.hasUI) {
 			ctx.ui.notify(
@@ -514,8 +539,12 @@ async function handleSessionBeforeCompact(event: SessionBeforeCompactEvent, ctx:
 	return undefined;
 }
 
-async function handleBeforeProviderRequest(event: BeforeProviderRequestEvent, ctx: ExtensionContext) {
-	const { config } = loadExtensionConfig();
+async function handleBeforeProviderRequest(
+	event: BeforeProviderRequestEvent,
+	ctx: ExtensionContext,
+	dependencies: ExtensionRuntimeDependencies,
+) {
+	const { config } = dependencies.loadExtensionConfig();
 	if (!config.enabled) {
 		return undefined;
 	}
@@ -638,9 +667,13 @@ async function handleBeforeProviderRequest(event: BeforeProviderRequestEvent, ct
 	return rewrite.rewrittenPayload;
 }
 
-export default function (pi: ExtensionAPI) {
+export function registerExtensionRuntime(
+	pi: ExtensionAPI,
+	dependencies: ExtensionRuntimeDependencies = DEFAULT_DEPENDENCIES,
+): void {
+	// Mid-run compaction is intentionally disabled regardless of config.
 	pi.on("session_start", (_event, ctx) => {
-		const { config, source, warnings } = loadExtensionConfig();
+		const { config, source, warnings } = dependencies.loadExtensionConfig();
 		if (!config.enabled) return;
 
 		if (warnings.length > 0 && ctx.hasUI && config.debug) {
@@ -669,11 +702,15 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
-	pi.on("session_before_compact", handleSessionBeforeCompact);
-	pi.on("before_provider_request", handleBeforeProviderRequest);
+	pi.on("session_before_compact", (event, ctx) =>
+		handleSessionBeforeCompact(event, ctx, dependencies),
+	);
+	pi.on("before_provider_request", (event, ctx) =>
+		handleBeforeProviderRequest(event, ctx, dependencies),
+	);
 
 	pi.on("session_compact_failed", (event, ctx) => {
-		const { config } = loadExtensionConfig();
+		const { config } = dependencies.loadExtensionConfig();
 		if (!config.enabled) return;
 
 		writeDebugArtifact(
@@ -691,3 +728,5 @@ export default function (pi: ExtensionAPI) {
 		);
 	});
 }
+
+export default registerExtensionRuntime;

package/src/midrun.ts

@@ -0,0 +1,229 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadExtensionConfig } from "./config";
+import { writeDebugArtifact } from "./debug";
+import { EXTENSION_ID, type LoadedExtensionConfig } from "./types";
+
+type MidRunPhase = "idle" | "abort-pending" | "compacting" | "resume-pending" | "failed";
+
+type MidRunState = {
+	phase: MidRunPhase;
+	generation: number;
+	sessionId?: string;
+	baselineCompactionId?: string;
+	triggerTokens?: number;
+	triggerPercent?: number;
+	triggerContextWindow?: number;
+};
+
+type ConfigLoader = () => LoadedExtensionConfig;
+
+const RESUME_CUSTOM_TYPE = "pi-better-compaction-midrun-resume";
+const RESUME_PROMPT = `[pi-better-compaction/midrun]
+Context compaction completed. Continue the interrupted task from the exact point where execution stopped.`;
+const MIDRUN_COMPACTION_INSTRUCTIONS =
+	"Preserve the active task, completed work, decisions, changed files, failures, current tool-loop state, and exact next steps so execution can resume immediately after compaction.";
+
+function getSessionId(ctx: ExtensionContext): string | undefined {
+	try {
+		return ctx.sessionManager.getSessionId();
+	} catch {
+		return undefined;
+	}
+}
+
+function getLatestCompactionId(ctx: ExtensionContext): string | undefined {
+	const branch = ctx.sessionManager.getBranch();
+	for (let index = branch.length - 1; index >= 0; index--) {
+		const entry = branch[index];
+		if (entry?.type === "compaction") return entry.id;
+	}
+	return undefined;
+}
+
+function resetState(state: MidRunState): void {
+	state.phase = "idle";
+	state.generation += 1;
+	state.sessionId = undefined;
+	state.baselineCompactionId = undefined;
+	state.triggerTokens = undefined;
+	state.triggerPercent = undefined;
+	state.triggerContextWindow = undefined;
+}
+
+function sameSession(state: MidRunState, ctx: ExtensionContext): boolean {
+	return state.sessionId !== undefined && state.sessionId === getSessionId(ctx);
+}
+
+function notifyFailure(ctx: ExtensionContext, message: string): void {
+	if (ctx.hasUI) {
+		ctx.ui.notify(`${EXTENSION_ID}: ${message}`, "error");
+	}
+}
+
+function scheduleResume(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	state: MidRunState,
+	generation: number,
+): void {
+	state.phase = "resume-pending";
+
+	setImmediate(() => {
+		if (
+			state.generation !== generation ||
+			state.phase !== "resume-pending" ||
+			!sameSession(state, ctx)
+		) {
+			return;
+		}
+
+		if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+			resetState(state);
+			return;
+		}
+
+		resetState(state);
+		pi.sendMessage(
+			{
+				customType: RESUME_CUSTOM_TYPE,
+				content: RESUME_PROMPT,
+				display: false,
+				details: { source: "midrun-compaction" },
+			},
+			{ triggerTurn: true },
+		);
+	});
+}
+
+export function registerMidRunGuard(
+	pi: ExtensionAPI,
+	loadConfig: ConfigLoader = loadExtensionConfig,
+): void {
+	const state: MidRunState = { phase: "idle", generation: 0 };
+
+	pi.on("turn_end", (event, ctx) => {
+		const { config } = loadConfig();
+		if (!config.enabled || !config.midRun.enabled || state.phase !== "idle") return;
+		if (event.toolResults.length === 0 || ctx.hasPendingMessages()) return;
+
+		const usage = ctx.getContextUsage();
+		if (!usage || usage.tokens == null || usage.percent == null) return;
+		if (usage.percent < config.midRun.thresholdPercent) return;
+
+		const sessionId = getSessionId(ctx);
+		if (!sessionId) return;
+
+		state.phase = "abort-pending";
+		state.generation += 1;
+		state.sessionId = sessionId;
+		state.baselineCompactionId = getLatestCompactionId(ctx);
+		state.triggerTokens = usage.tokens;
+		state.triggerPercent = usage.percent;
+		state.triggerContextWindow = usage.contextWindow;
+
+		writeDebugArtifact(
+			"lifecycle",
+			{
+				event: "midrun.threshold",
+				turnIndex: event.turnIndex,
+				tokens: usage.tokens,
+				contextWindow: usage.contextWindow,
+				percent: usage.percent,
+				thresholdPercent: config.midRun.thresholdPercent,
+				baselineCompactionId: state.baselineCompactionId,
+			},
+			config,
+			ctx,
+		);
+
+		// Never compact while the agent run is active; let Pi settle first.
+		ctx.abort();
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (state.phase !== "abort-pending") return;
+		if (!sameSession(state, ctx)) {
+			resetState(state);
+			return;
+		}
+
+		// An earlier agent_settled handler may already have started or queued another run.
+		if (!ctx.isIdle() || ctx.hasPendingMessages()) {
+			resetState(state);
+			return;
+		}
+
+		const generation = state.generation;
+		const latestCompactionId = getLatestCompactionId(ctx);
+		if (latestCompactionId !== state.baselineCompactionId) {
+			const { config } = loadConfig();
+			writeDebugArtifact(
+				"lifecycle",
+				{
+					event: "midrun.coalesced",
+					reason: "compaction-already-occurred-during-abort",
+					baselineCompactionId: state.baselineCompactionId,
+					latestCompactionId,
+				},
+				config,
+				ctx,
+			);
+			scheduleResume(pi, ctx, state, generation);
+			return;
+		}
+
+		const { config } = loadConfig();
+		if (!config.enabled || !config.midRun.enabled) {
+			scheduleResume(pi, ctx, state, generation);
+			return;
+		}
+
+		const usage = ctx.getContextUsage();
+		if (usage?.percent != null && usage.percent < config.midRun.thresholdPercent) {
+			scheduleResume(pi, ctx, state, generation);
+			return;
+		}
+
+		state.phase = "compacting";
+		ctx.compact({
+			customInstructions: MIDRUN_COMPACTION_INSTRUCTIONS,
+			onComplete: () => {
+				if (
+					state.generation !== generation ||
+					state.phase !== "compacting" ||
+					!sameSession(state, ctx)
+				) {
+					return;
+				}
+				scheduleResume(pi, ctx, state, generation);
+			},
+			onError: (error) => {
+				if (state.generation !== generation || !sameSession(state, ctx)) return;
+
+				const latest = getLatestCompactionId(ctx);
+				if (/Already compacted/i.test(error.message) && latest !== state.baselineCompactionId) {
+					scheduleResume(pi, ctx, state, generation);
+					return;
+				}
+
+				state.phase = "failed";
+				writeDebugArtifact(
+					"lifecycle",
+					{
+						event: "midrun.failed",
+						errorMessage: error.message,
+						triggerTokens: state.triggerTokens,
+						triggerPercent: state.triggerPercent,
+						triggerContextWindow: state.triggerContextWindow,
+					},
+					config,
+					ctx,
+				);
+				notifyFailure(ctx, `mid-run compaction failed: ${error.message}`);
+			},
+		});
+	});
+
+	pi.on("session_start", () => resetState(state));
+	pi.on("session_shutdown", () => resetState(state));
+}

package/src/types.ts

@@ -33,8 +33,14 @@ export type DebugArtifactKind =
 	| "compaction-event"
 	| "lifecycle";
 
+export type MidRunConfig = {
+	enabled: boolean;
+	thresholdPercent: number;
+};
+
 export type ExtensionConfig = {
 	enabled: boolean;
+	midRun: MidRunConfig;
 	/**
 	 * Allow a Responses session whose latest compaction was not created by this extension
 	 * to restart native compaction from Pi's current serialized session context.
@@ -304,6 +310,10 @@ export function createNativeCompactionResult(
 
 export const DEFAULT_EXTENSION_CONFIG: ExtensionConfig = {
 	enabled: true,
+	midRun: {
+		enabled: false,
+		thresholdPercent: 80,
+	},
 	allowCompactionContinuityBreak: false,
 	compactionModel: undefined,
 	compactionThinkingLevel: "off",