@vanillagreen/pi-qol 1.1.1 → 1.3.0

package/README.md

@@ -50,6 +50,7 @@ Restart Pi after installation.
 | `/context` | Show inline context-window usage, model/context limit, and estimated category breakdowns. |
 | `/search [query]` | Open previous-session search, optionally prefilled with a query. |
 | `/search:refresh` | Refresh the session search cache. |
+| `/search:resume-pending <id>` | Internal recovery command inserted into the editor when a resume/fork action must be confirmed by pressing Enter. |
 | `/handoff <goal>` | Draft a focused handoff prompt for a new session. |
 
 `/qol` and `/search` arguments support autocomplete.
@@ -63,6 +64,7 @@ Settings are exposed through `pi-extension-manager` under **QOL**.
 - `replaceFooter`: hide Pi's default footer while QOL's compact statusline is active; default on.
 - `compactPrompt`: use the compact `π` prompt editor; default on.
 - `showSessionNameTitle`: show the named session above the prompt, or in tmux's pane title/border; default on.
+- `showSessionNameWindow`: also rename the current tmux window to `π <session>` so it appears in the tmux status line. Disables `automatic-rename` for the window while active and restores it on shutdown. Requires `showSessionNameTitle`; default on.
 - `inputBottomPaddingLines`: blank lines below the compact prompt; default `0`.
 - Git display knobs: `gitRefreshTimeoutMs`, `showDirtyMarker`.
 - If `pi-caveman` is loaded, QOL reads its bridge to show a Caveman icon in the statusline and to make `Alt+C` cycle Caveman modes. The Caveman package's `showStatusBadge` setting also controls this QOL badge.

package/extensions/qol/agent-end.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function textFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (typeof part === "string") return part;
+			if (part && typeof part === "object" && (part as any).type === "text" && typeof (part as any).text === "string") return (part as any).text;
+			return "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+export function lastAssistantTextFromAgentEnd(event: any, ctx: ExtensionContext): string {
+	const eventMessages = Array.isArray(event?.messages) ? event.messages : [];
+	for (let index = eventMessages.length - 1; index >= 0; index -= 1) {
+		const message = eventMessages[index];
+		if (message?.role === "assistant") return textFromContent(message.content);
+	}
+	const branch = ctx.sessionManager.getBranch?.() ?? [];
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index] as any;
+		if (entry?.type === "message" && entry.message?.role === "assistant") return textFromContent(entry.message.content);
+	}
+	return "";
+}
+
+export function needsDirection(text: string): boolean {
+	return /\?\s*$|\b(let me know|tell me|which (one|option)|choose|confirm|approve|should i|would you like|do you want|need your input|awaiting|next step)\b/i.test(text);
+}
+
+export function criticalInfo(text: string): string | undefined {
+	const match = text.match(/\b(critical|urgent|warning|blocked|cannot proceed|security|vulnerab|secret|credential|rate limit|context (overflow|full)|manual action required)\b/i);
+	if (!match) return undefined;
+	const line = text.split(/\r?\n/).find((candidate) => candidate.toLowerCase().includes(match[0].toLowerCase())) ?? text;
+	return line.trim();
+}
+
+export function taskStats(state: any): { completed: number; remaining: number; total: number } | undefined {
+	const tasks = Array.isArray(state?.tasks) ? state.tasks : undefined;
+	if (!tasks) return undefined;
+	const total = tasks.length;
+	const completed = tasks.filter((task: any) => task?.status === "completed").length;
+	const remaining = tasks.filter((task: any) => task?.status === "pending" || task?.status === "in_progress").length;
+	return { completed, remaining, total };
+}

package/extensions/qol/agent-statusline.ts

@@ -0,0 +1,52 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { readPiAgentsStatuslineBridge } from "./bridges.js";
+
+type AgentAsciiColor = "red" | "green" | "yellow" | "blue" | "magenta" | "cyan";
+
+const AGENT_ASCII_COLOR_SEQUENCE: AgentAsciiColor[] = ["magenta", "green", "blue", "cyan", "yellow", "red"];
+const AGENT_ASCII_BG: Record<AgentAsciiColor, number> = {
+	red: 41,
+	green: 42,
+	yellow: 43,
+	blue: 44,
+	magenta: 45,
+	cyan: 46,
+};
+
+function normalizeAgentAsciiColor(value: string | undefined): AgentAsciiColor | undefined {
+	const normalized = value?.trim().toLowerCase().replace(/[^a-z]/g, "");
+	switch (normalized) {
+		case "red": return "red";
+		case "green": return "green";
+		case "yellow":
+		case "orange": return "yellow";
+		case "blue": return "blue";
+		case "magenta":
+		case "purple":
+		case "violet": return "magenta";
+		case "cyan":
+		case "teal": return "cyan";
+		default: return undefined;
+	}
+}
+
+function fallbackAgentAsciiColor(name: string): AgentAsciiColor {
+	let hash = 0;
+	for (const char of name) hash = ((hash * 31) + char.charCodeAt(0)) >>> 0;
+	return AGENT_ASCII_COLOR_SEQUENCE[hash % AGENT_ASCII_COLOR_SEQUENCE.length] ?? "magenta";
+}
+
+function ansiAgentBg(color: AgentAsciiColor, text: string): string {
+	return `\x1b[30;${AGENT_ASCII_BG[color]}m${text}\x1b[39;49m`;
+}
+
+export function subagentStatuslineMarker(cwd: string, maxInnerWidth = 24): { plain: string; styled: string } | undefined {
+	const bridgeInfo = readPiAgentsStatuslineBridge()?.getCurrentSubagent(cwd);
+	const envName = process.env.PI_SUBAGENT_CHILD_AGENT?.trim();
+	const rawName = bridgeInfo?.name?.trim() || envName;
+	if (!rawName) return undefined;
+	const color = normalizeAgentAsciiColor(bridgeInfo?.color) ?? normalizeAgentAsciiColor(process.env.PI_SUBAGENT_CHILD_COLOR) ?? fallbackAgentAsciiColor(rawName);
+	const inner = truncateToWidth(rawName, Math.max(1, maxInnerWidth), "…");
+	const plain = ` ${inner} `;
+	return { plain, styled: ansiAgentBg(color, plain) };
+}

package/extensions/qol/ansi.ts

@@ -0,0 +1,115 @@
+const ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/g;
+
+export const ANSI_ESCAPE_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+export const ANSI_GREEN_FG = "\x1b[32m";
+export const ANSI_RED_FG = "\x1b[31m";
+export const ANSI_YELLOW_FG = "\x1b[33m";
+export const ANSI_FG_RESET = "\x1b[39m";
+
+export function stripAnsi(text: string): string {
+	return text.replace(ANSI_PATTERN, "");
+}
+
+export function ansiGreen(text: string): string {
+	return `${ANSI_GREEN_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function ansiRed(text: string): string {
+	return `${ANSI_RED_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function ansiYellow(text: string): string {
+	return `${ANSI_YELLOW_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function oneLine(text: string): string {
+	return text
+		.replace(ANSI_ESCAPE_RE, "")
+		.replace(/[\r\n\t]+/g, " ")
+		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export interface VisibleMap {
+	text: string;
+	rawIndexByVisibleIndex: number[];
+}
+
+export interface VisibleReplacement {
+	start: number;
+	end: number;
+	text: string;
+}
+
+export function ansiSequenceEnd(input: string, start: number): number {
+	const introducer = input[start + 1];
+	if (introducer == null) return start + 1;
+
+	// OSC, DCS, APC, PM, SOS strings are zero-width and end in ST (ESC \\).
+	// OSC may also end in BEL.
+	if (introducer === "]" || introducer === "P" || introducer === "_" || introducer === "^" || introducer === "X") {
+		const st = input.indexOf("\x1b\\", start + 2);
+		const bell = introducer === "]" ? input.indexOf("\x07", start + 2) : -1;
+		if (bell >= 0 && (st < 0 || bell < st)) return bell + 1;
+		return st >= 0 ? st + 2 : input.length;
+	}
+
+	if (introducer === "[") {
+		let index = start + 2;
+		while (index < input.length) {
+			const code = input.charCodeAt(index);
+			if (code >= 0x40 && code <= 0x7e) return index + 1;
+			index += 1;
+		}
+		return input.length;
+	}
+
+	return Math.min(start + 2, input.length);
+}
+
+export function buildVisibleMap(input: string): VisibleMap {
+	const rawIndexByVisibleIndex: number[] = [0];
+	let text = "";
+	let index = 0;
+
+	while (index < input.length) {
+		if (input.charCodeAt(index) === 0x1b) {
+			index = ansiSequenceEnd(input, index);
+			continue;
+		}
+
+		if (rawIndexByVisibleIndex[text.length] === undefined) rawIndexByVisibleIndex[text.length] = index;
+		text += input[index] ?? "";
+		index += 1;
+		rawIndexByVisibleIndex[text.length] = index;
+	}
+
+	if (rawIndexByVisibleIndex[text.length] === undefined) rawIndexByVisibleIndex[text.length] = index;
+	return { rawIndexByVisibleIndex, text };
+}
+
+export function applyVisibleReplacements(input: string, map: VisibleMap, replacements: VisibleReplacement[]): string {
+	if (replacements.length === 0) return input;
+
+	const sorted = replacements
+		.filter((replacement) => replacement.end > replacement.start)
+		.sort((a, b) => a.start - b.start || b.end - a.end);
+
+	let output = "";
+	let lastRawIndex = 0;
+	let lastVisibleIndex = 0;
+
+	for (const replacement of sorted) {
+		if (replacement.start < lastVisibleIndex) continue;
+		const rawStart = map.rawIndexByVisibleIndex[replacement.start];
+		const rawEnd = map.rawIndexByVisibleIndex[replacement.end];
+		if (rawStart == null || rawEnd == null || rawStart < lastRawIndex) continue;
+
+		output += input.slice(lastRawIndex, rawStart) + replacement.text;
+		lastRawIndex = rawEnd;
+		lastVisibleIndex = replacement.end;
+	}
+
+	return output + input.slice(lastRawIndex);
+}

package/extensions/qol/bridges.ts

@@ -0,0 +1,78 @@
+import {
+	CAVEMAN_BRIDGE_SYMBOL,
+	PI_AGENTS_STATUSLINE_SYMBOL,
+	QUESTION_SERVICE_SYMBOL,
+	VSTACK_MODAL_LOCK_SYMBOL,
+} from "./constants.js";
+
+export interface CavemanBridge {
+	isActive(): boolean;
+	getMode(): string;
+	getConfiguredMode?(cwd?: string): string;
+	getLastActiveMode(): string;
+	hasSessionOverride?(): boolean;
+	isStatusBadgeEnabled?(cwd?: string): boolean;
+	cycleMode?(cwd?: string): string;
+	setMode?(mode: string, cwd?: string): string | undefined;
+	subscribe(listener: () => void): () => void;
+}
+
+export interface PiAgentsStatuslineBridge {
+	getCurrentSubagent(cwd?: string): { name: string; color?: string } | undefined;
+}
+
+export interface QuestionRequestLike {
+	header?: string;
+	question?: string;
+}
+
+export interface QuestionOpenedEventLike {
+	requestId?: string;
+	request?: QuestionRequestLike;
+	source?: string;
+}
+
+export interface QuestionServiceLike {
+	listPending(): unknown[];
+	subscribe(listener: (event: any) => void): () => void;
+}
+
+interface VstackModalLock {
+	depth: number;
+}
+
+export function readCavemanBridge(): CavemanBridge | undefined {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const value = host[CAVEMAN_BRIDGE_SYMBOL];
+	return value && typeof value === "object" ? (value as CavemanBridge) : undefined;
+}
+
+export function readPiAgentsStatuslineBridge(): PiAgentsStatuslineBridge | undefined {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const value = host[PI_AGENTS_STATUSLINE_SYMBOL];
+	return value && typeof value === "object" && typeof (value as PiAgentsStatuslineBridge).getCurrentSubagent === "function"
+		? (value as PiAgentsStatuslineBridge)
+		: undefined;
+}
+
+export function getQuestionService(): QuestionServiceLike | undefined {
+	const service = (globalThis as unknown as Record<PropertyKey, unknown>)[QUESTION_SERVICE_SYMBOL];
+	if (!service || typeof service !== "object") return undefined;
+	const candidate = service as Partial<QuestionServiceLike>;
+	if (typeof candidate.subscribe === "function" && typeof candidate.listPending === "function") return candidate as QuestionServiceLike;
+	return undefined;
+}
+
+export function acquireVstackModalLock(): () => void {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const existing = host[VSTACK_MODAL_LOCK_SYMBOL] as VstackModalLock | undefined;
+	const lock = existing && typeof existing.depth === "number" ? existing : { depth: 0 };
+	host[VSTACK_MODAL_LOCK_SYMBOL] = lock;
+	lock.depth += 1;
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		lock.depth = Math.max(0, lock.depth - 1);
+	};
+}

package/extensions/qol/compaction.ts

@@ -0,0 +1,264 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { complete, type Message } from "@earendil-works/pi-ai";
+import { convertToLlm, serializeConversation, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_COMPACTION_MAX_TOKENS,
+	DEFAULT_COMPACTION_MODEL,
+	DEFAULT_IDLE_COMPACTION_THRESHOLD_TOKENS,
+	QOL_COMPACTION_SYSTEM_PROMPT,
+} from "./constants.js";
+import { settingBoolean, settingNumber, settingString } from "./settings.js";
+import { stringifyError } from "./util.js";
+
+export type QolSummaryProfile = "concise" | "balanced" | "exhaustive";
+export type QolSummaryPurpose = "compaction" | "branch-summary" | "session-search";
+
+export function compactionNotify(ctx: ExtensionContext, message: string, level: "info" | "warning" | "error" = "info"): void {
+	if (ctx.hasUI && settingBoolean("compaction.notify", true, ctx.cwd)) ctx.ui.notify(message, level);
+}
+
+export function compactionProfile(cwd: string): QolSummaryProfile {
+	const value = settingString("compaction.profile", "balanced", cwd);
+	return value === "concise" || value === "exhaustive" ? value : "balanced";
+}
+
+function compactionProfileInstructions(profile: QolSummaryProfile): string {
+	if (profile === "concise") return "Prefer a compact continuation summary. Include only decisions, current state, modified/read files, blockers, and concrete next steps.";
+	if (profile === "exhaustive") return "Be thorough. The summary may replace substantial conversation history, so preserve all relevant implementation details, alternatives considered, exact file paths, commands, errors, and pending work.";
+	return "Be complete but not verbose. Preserve enough detail for a future assistant to continue without the old transcript.";
+}
+
+function stripThinkingForSummary(messages: Message[]): Message[] {
+	return messages.map((message) => {
+		if (message.role !== "assistant" || !Array.isArray(message.content)) return message;
+		return {
+			...message,
+			content: message.content.filter((part: any) => part?.type !== "thinking"),
+		};
+	});
+}
+
+export function serializeMessagesForSummary(messages: AgentMessage[]): string {
+	return serializeConversation(stripThinkingForSummary(convertToLlm(messages)));
+}
+
+function customMessageContentToText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const part of content) {
+		if (part?.type === "text" && typeof part.text === "string") parts.push(part.text);
+		else if (part?.type === "image") parts.push(`[image${typeof part.mimeType === "string" ? ` ${part.mimeType}` : ""}]`);
+		else if (part?.type) parts.push(`[${String(part.type)}]`);
+	}
+	return parts.join("\n").trim();
+}
+
+function buildSummaryPrompt(options: {
+	conversationText: string;
+	customInstructions?: string;
+	previousSummary?: string;
+	profile: QolSummaryProfile;
+	purpose: QolSummaryPurpose;
+}): string {
+	const purposeText = options.purpose === "branch-summary"
+		? "the branch being left during /tree navigation"
+		: options.purpose === "session-search"
+			? "the previous session being imported into the current context"
+			: "the conversation span being compacted";
+	const previous = options.previousSummary ? `<previous-summary>\n${options.previousSummary}\n</previous-summary>\n\n` : "";
+	const custom = options.customInstructions?.trim() ? `<custom-instructions>\n${options.customInstructions.trim()}\n</custom-instructions>\n\n` : "";
+	return `${custom}${previous}<conversation>\n${options.conversationText}\n</conversation>\n\nSummarize ${purposeText} for a coding agent that must continue the work.\n\n${compactionProfileInstructions(options.profile)}\n\nUse this markdown shape:\n\n## Goal\n[What the user is trying to accomplish]\n\n## Constraints & Preferences\n- [Requirements, style, safety, or user preferences]\n\n## Progress\n### Done\n- [x] [Completed work]\n\n### In Progress\n- [ ] [Current partial work]\n\n### Blocked\n- [Blockers or none]\n\n## Key Decisions\n- **[Decision]**: [Rationale]\n\n## Files & Commands\n- [Files read/modified and important commands/results]\n\n## Next Steps\n1. [Most important next action]\n\n## Critical Context\n- [Anything easy to lose but needed later]`;
+}
+
+async function summarizeWithRemote(endpoint: string, systemPrompt: string, promptText: string, maxTokens: number, signal?: AbortSignal): Promise<string> {
+	const response = await fetch(endpoint, {
+		body: JSON.stringify({ maxTokens, prompt: promptText, systemPrompt }),
+		headers: { "content-type": "application/json" },
+		method: "POST",
+		signal,
+	});
+	const text = await response.text();
+	if (!response.ok) throw new Error(`Remote compaction endpoint returned ${response.status}: ${text.slice(0, 500)}`);
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		throw new Error("Remote compaction endpoint did not return JSON");
+	}
+	if (parsed && typeof parsed === "object") {
+		const record = parsed as Record<string, unknown>;
+		if (typeof record.summary === "string") return record.summary;
+		if (typeof record.text === "string") return record.text;
+	}
+	throw new Error("Remote compaction response missing summary");
+}
+
+export function resolveConfiguredModel(ctx: ExtensionContext, configured: string): any | undefined {
+	if (!configured || configured === "current") return ctx.model;
+	const withoutThinking = configured.replace(/:(off|minimal|low|medium|high|xhigh)$/i, "");
+	const slash = withoutThinking.indexOf("/");
+	if (slash > 0) return ctx.modelRegistry.find(withoutThinking.slice(0, slash), withoutThinking.slice(slash + 1));
+	const providers = [ctx.model?.provider, "google", "openai", "anthropic", "mistral", "moonshot", "cloudflare-ai-gateway", "cloudflare-workers-ai"].filter((value): value is string => typeof value === "string");
+	for (const provider of providers) {
+		const model = ctx.modelRegistry.find(provider, withoutThinking);
+		if (model) return model;
+	}
+	return undefined;
+}
+
+export function modelLabel(model: any): string {
+	return model ? `${model.provider}/${model.id}` : "unknown model";
+}
+
+export async function generateQolSummary(ctx: ExtensionContext, options: {
+	conversationText: string;
+	customInstructions?: string;
+	previousSummary?: string;
+	maxTokens?: number;
+	model?: string;
+	purpose: QolSummaryPurpose;
+	signal?: AbortSignal;
+}): Promise<{ model: string; summary: string; via: "model" | "remote" }> {
+	const maxTokens = Math.max(256, Math.floor(options.maxTokens ?? settingNumber("compaction.maxTokens", DEFAULT_COMPACTION_MAX_TOKENS, ctx.cwd)));
+	const promptText = buildSummaryPrompt({
+		conversationText: options.conversationText,
+		customInstructions: options.customInstructions,
+		previousSummary: settingBoolean("compaction.includePreviousSummary", true, ctx.cwd) ? options.previousSummary : undefined,
+		profile: compactionProfile(ctx.cwd),
+		purpose: options.purpose,
+	});
+
+	const remoteEndpoint = settingString("compaction.remoteEndpoint", "", ctx.cwd);
+	if (settingBoolean("compaction.remoteEnabled", false, ctx.cwd) && remoteEndpoint) {
+		try {
+			const summary = await summarizeWithRemote(remoteEndpoint, QOL_COMPACTION_SYSTEM_PROMPT, promptText, maxTokens, options.signal);
+			return { model: remoteEndpoint, summary, via: "remote" };
+		} catch (error) {
+			compactionNotify(ctx, `Remote compaction failed, trying model fallback: ${stringifyError(error)}`, "warning");
+		}
+	}
+
+	const configuredModel = options.model ?? settingString("compaction.model", DEFAULT_COMPACTION_MODEL, ctx.cwd);
+	const model = resolveConfiguredModel(ctx, configuredModel);
+	if (!model) throw new Error(`Summary model not found: ${configuredModel}`);
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) throw new Error(auth.error);
+	if (!auth.apiKey) throw new Error(`No API key for ${model.provider}`);
+
+	const message: Message = {
+		content: [{ text: promptText, type: "text" }],
+		role: "user",
+		timestamp: Date.now(),
+	};
+	const response = await complete(
+		model,
+		{ messages: [message], systemPrompt: QOL_COMPACTION_SYSTEM_PROMPT },
+		{ apiKey: auth.apiKey, headers: auth.headers, maxTokens, signal: options.signal },
+	);
+	const summary = response.content
+		.filter((content): content is { type: "text"; text: string } => content.type === "text")
+		.map((content) => content.text)
+		.join("\n")
+		.trim();
+	return { model: modelLabel(model), summary, via: "model" };
+}
+
+export async function handleQolCompaction(event: any, ctx: ExtensionContext): Promise<any> {
+	if (!settingBoolean("compaction.customEnabled", false, ctx.cwd)) return undefined;
+	const preparation = event.preparation ?? {};
+	const messages = [...(preparation.messagesToSummarize ?? []), ...(preparation.turnPrefixMessages ?? [])];
+	if (messages.length === 0) return undefined;
+	const tokensBefore = typeof preparation.tokensBefore === "number" ? preparation.tokensBefore : 0;
+	compactionNotify(ctx, `QOL compaction: summarizing ${messages.length} message(s), ${tokensBefore.toLocaleString()} token(s).`, "info");
+	try {
+		const conversationText = serializeMessagesForSummary(messages);
+		const result = await generateQolSummary(ctx, {
+			conversationText,
+			customInstructions: event.customInstructions,
+			previousSummary: preparation.previousSummary,
+			purpose: "compaction",
+			signal: event.signal,
+		});
+		if (!result.summary.trim()) throw new Error("Compaction summary was empty");
+		compactionNotify(ctx, `QOL compaction complete via ${result.via}: ${result.model}`, "info");
+		return {
+			compaction: {
+				details: {
+					messageCount: messages.length,
+					model: result.model,
+					profile: compactionProfile(ctx.cwd),
+					source: "pi-qol",
+					via: result.via,
+				},
+				firstKeptEntryId: preparation.firstKeptEntryId,
+				summary: result.summary,
+				tokensBefore: preparation.tokensBefore,
+			},
+		};
+	} catch (error) {
+		if (event.signal?.aborted) return undefined;
+		compactionNotify(ctx, `QOL compaction failed: ${stringifyError(error)}`, "error");
+		return settingBoolean("compaction.fallbackToDefault", true, ctx.cwd) ? undefined : { cancel: true };
+	}
+}
+
+function summarizeEntryForBranch(entry: any): string[] {
+	if (entry?.type === "message" && entry.message) return [serializeMessagesForSummary([entry.message])];
+	if (entry?.type === "compaction" && typeof entry.summary === "string") return [`[Compaction summary]: ${entry.summary}`];
+	if (entry?.type === "branch_summary" && typeof entry.summary === "string") return [`[Branch summary]: ${entry.summary}`];
+	if (entry?.type === "custom_message") return [`[Custom message${entry.customType ? `:${entry.customType}` : ""}]: ${customMessageContentToText(entry.content) || "[empty]"}`];
+	return [];
+}
+
+export async function handleQolBranchSummary(event: any, ctx: ExtensionContext): Promise<any> {
+	if (!settingBoolean("compaction.branchSummaryEnabled", false, ctx.cwd)) return undefined;
+	const preparation = event.preparation ?? {};
+	if (preparation.userWantsSummary !== true) return undefined;
+	const entries = Array.isArray(preparation.entriesToSummarize) ? preparation.entriesToSummarize : [];
+	const conversationText = entries.flatMap(summarizeEntryForBranch).join("\n\n").trim();
+	if (!conversationText) return undefined;
+	compactionNotify(ctx, `QOL branch summary: summarizing ${entries.length} entr${entries.length === 1 ? "y" : "ies"}.`, "info");
+	try {
+		const result = await generateQolSummary(ctx, {
+			conversationText,
+			customInstructions: event.customInstructions ?? preparation.customInstructions,
+			purpose: "branch-summary",
+			signal: event.signal,
+		});
+		if (!result.summary.trim()) throw new Error("Branch summary was empty");
+		return {
+			summary: {
+				details: { entryCount: entries.length, model: result.model, profile: compactionProfile(ctx.cwd), source: "pi-qol", via: result.via },
+				summary: result.summary,
+			},
+		};
+	} catch (error) {
+		if (event.signal?.aborted) return undefined;
+		compactionNotify(ctx, `QOL branch summary failed: ${stringifyError(error)}`, "error");
+		return undefined;
+	}
+}
+
+function contextUsage(ctx: ExtensionContext): { contextWindow?: number; tokens: number } | undefined {
+	const usage = ctx.getContextUsage?.() as { tokens?: unknown; contextWindow?: unknown } | undefined;
+	const tokens = Number(usage?.tokens);
+	if (!Number.isFinite(tokens) || tokens <= 0) return undefined;
+	const contextWindow = Number(usage?.contextWindow ?? ctx.model?.contextWindow);
+	return { contextWindow: Number.isFinite(contextWindow) && contextWindow > 0 ? contextWindow : undefined, tokens };
+}
+
+export function compactionTriggerReason(ctx: ExtensionContext): string | undefined {
+	const usage = contextUsage(ctx);
+	if (!usage) return undefined;
+	const tokenLimit = settingNumber("compaction.thresholdTokens", -1, ctx.cwd);
+	if (tokenLimit > 0 && usage.tokens >= tokenLimit) return `${usage.tokens.toLocaleString()} tokens >= ${Math.floor(tokenLimit).toLocaleString()} token limit`;
+	const percentLimit = settingNumber("compaction.thresholdPercent", -1, ctx.cwd);
+	if (percentLimit > 0 && usage.contextWindow) {
+		const percent = (usage.tokens / usage.contextWindow) * 100;
+		if (percent >= percentLimit) return `${percent.toFixed(1)}% context >= ${percentLimit}% limit`;
+	}
+	const idleLimit = settingNumber("compaction.idleThresholdTokens", DEFAULT_IDLE_COMPACTION_THRESHOLD_TOKENS, ctx.cwd);
+	if (usage.tokens >= idleLimit) return `${usage.tokens.toLocaleString()} tokens >= ${Math.floor(idleLimit).toLocaleString()} idle threshold`;
+	return undefined;
+}