@vanillagreen/pi-qol 1.4.3 → 1.6.0

package/README.md

@@ -5,16 +5,18 @@
 ![Session search popup](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/session-search.gif)
 ![/context usage breakdown](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/context-usage.png)
 
-Quality-of-life extension for Pi: compact statusline, multiline input, session naming and search, notifications, and a permission gate.
+Quality-of-life extension for Pi: compact statusline, multiline input, session naming and search, scheduled prompts, notifications, and a permission gate.
 
 ## Highlights
 
-- Compact statusline with repo, branch, model, thinking level, and context percent.
+- Compact statusline with repo, branch, model, thinking level, and context percent; can be disabled.
 - Newline-insert in the editor (multi-line drafts without auto-submit), with a fallback binding for terminals that can't distinguish the primary key.
 - Sessions auto-name from your first prompt. `/rename` overrides anytime.
 - `/search` browses previous sessions with snippet previews; the configured shortcut opens it instantly.
 - `/context` shows a Claude-style context-window breakdown.
 - `/handoff <goal>` drafts a focused prompt for a new session.
+- `/schedule 20m <message>` sends a delayed prompt without invoking the model until the timer fires.
+- Optional rate-limit auto-resume sends a configurable continuation after reset.
 - Permission gate prompts before risky `bash` commands. Default match: `rm -Rf`.
 - Notifications for ready, questions, blocked states, and task completion.
 - Thinking timer next to collapsed `Thinking...` labels.
@@ -51,19 +53,25 @@ Restart Pi after installation.
 | `/search [query]` | Open previous-session search. |
 | `/search:refresh` | Refresh the session search cache. |
 | `/handoff <goal>` | Draft a handoff prompt for a new session. |
+| `/schedule <delay> <message>` | Send a user message after a timer without invoking the model now. Example: `/schedule 20m retry the previous request`. |
 
 Arguments support autocomplete.
 
+`/schedule` accepts `ms`, `s`, `m`, `h`, and `d` units; bare numbers mean minutes. Pending prompts render above the statusline like steering/follow-up previews until they are sent or cancelled. Manage pending prompts with `/schedule list` and `/schedule cancel <id|all>`. Schedules are stored in the Pi session and re-armed on reload/resume; if Pi is not running at the due time, an overdue prompt sends when that session is next loaded.
+
 ## Settings
 
 Open `/extensions:settings`; settings appear under the **QOL** tab. Names below match the labels shown there.
 
+Glyph style: each package exposes `glyphStyle` (`unicode` default, `ascii` for terminal-safe chrome). `@vanillagreen/pi-tool-renderer.globalGlyphStyleOverride=ascii` forces ASCII chrome across vstack Pi extensions while leaving tool/model/user content unchanged.
+
 ### Statusline
 
 | Setting | What it does |
 | --- | --- |
 | Enable QOL editor helpers | Master toggle for QOL statusline, commands, notifications, search, compaction, and editor helpers. |
-| Replace built-in footer | Hide Pi's default footer while the QOL statusline is active. |
+| Show compact statusline | Render or disable the QOL statusline row. |
+| Replace built-in footer | Hide Pi's default footer while the QOL statusline is enabled. |
 | Use π prompt editor | Use the compact prompt editor. |
 | Show session name title | Show the session name above the prompt and in the tmux pane title. |
 | Sync session name to tmux window name | Rename the tmux window to `π <session>`. |
@@ -80,11 +88,13 @@ Open `/extensions:settings`; settings appear under the **QOL** tab. Names below
 | Style image chips | Render `[Image #N]` placeholders as distinct chips. |
 | Show attachment count | Show a status badge when the draft has image placeholders. |
 
-### Session naming
+### Session
 
 | Setting | What it does |
 | --- | --- |
 | Enable /rename command | Register the `/rename` command. |
+| Enable /schedule command | Register `/schedule` for timer-based prompts, useful for retrying after rate limits reset. |
+| Auto-resume after rate limits | Send the configured continuation after a detected reset; cancels on newer turn. |
 | Auto-name new sessions | Generate a friendly session name from the first prompt. |
 | Auto-rename model | Model used for title generation. |
 | Auto-rename fallback model | Model tried when the primary fails. |
@@ -107,6 +117,8 @@ Advanced: input cap, title length, output tokens, timeout, custom prompt templat
 | --- | --- |
 | Enable /context command | Register `/context`. |
 
+`/context` also estimates the serialized payload size of the messages that would be sent on the next request. When that payload crosses **Transcript-risk warn budget (chars)** a `Transcript risk` block appears below the compact buffer section even if token count is still under the context window — useful for catching large blob-shaped tool outputs that inflate the request long before token count alone would page anyone. If transcript-risk estimation itself errors, `/context` shows a sanitized error in the same block rather than silently hiding the warning.
+
 ### Session search
 
 | Setting | What it does |
@@ -154,7 +166,7 @@ Off by default. When enabled, non-interactive matches are blocked.
 | Setting | What it does |
 | --- | --- |
 | Custom compaction summaries | Use QOL summaries instead of Pi's default. |
-| Compaction model | Summarizer model. |
+| Compaction model | Summarizer model. Defaults to `current`, meaning Pi's active model; set a provider/model when you want a dedicated larger-context summarizer. |
 | Compaction detail profile | `concise`, `balanced`, or `exhaustive`. |
 | Include previous summary | Pass the previous summary for iterative continuity. |
 | Fallback to Pi default compaction | Run Pi's default compaction if QOL's fails. |
@@ -165,6 +177,27 @@ Off by default. When enabled, non-interactive matches are blocked.
 
 Idle thresholds (token threshold, idle delay, fixed token limit, percent limit) tune when idle compaction fires.
 
+### Long-session budget guard
+
+For autonomous/Flightdeck-style runs the agent never goes idle, so idle compaction may never fire and the transcript can grow until provider/buffer limits hit. The budget guard runs on `agent_end` (not idle) and starts a compaction immediately when context usage crosses a percent of the model window or an absolute token limit. It fires once per threshold crossing — repeated `agent_end` events above the same threshold do not retrigger it, and the crossing key resets on a successful compaction or on a transient compaction failure (so the next `agent_end` retries).
+
+| Setting | What it does | Default |
+| --- | --- | --- |
+| Long-session budget guard | Master toggle for the agent_end budget guard. | on |
+| Budget guard percent | Context-window percentage that fires the guard. `-1` disables percent-based firing. | `85` |
+| Budget guard token limit | Absolute tokens that fire the guard. `-1` uses percent only. | `-1` |
+| Chunked compaction input cap | Max serialized characters per summarization request. Long transcripts are chunked, summarized chunk-by-chunk, then tree-reduced — every model/remote request (chunk + every reduce pass) is bounded so the compaction call itself cannot exceed provider buffer limits. `0` disables chunking. | `240000` |
+| Write pre-compaction handoff artifact | Before compaction, write `~/.pi/agent/vstack/sessions/<session>/pi-qol/handoff/<timestamp>.json` plus a `latest.json` pointer containing previous summary, last task state, and referenced files/artifacts. Write failures surface as a QOL warning notification and a `handoffArtifactError` field in the compaction details. | on |
+| Transcript-risk warn budget (chars) | `/context` shows a warning when the serialized payload of messages-to-send exceeds this many characters, even if tokens are still below the context window. `0` disables. | `600000` |
+
+When the budget guard fires it injects a sentinel into the compaction request so the QOL bounded handler always runs — chunked summarizer + handoff artifact — even if **Custom compaction summaries** is off. Manual compactions (`/tree`, idle compaction, user-triggered) still only use the QOL handler when **Custom compaction summaries** is on; otherwise they fall through to Pi's default compaction with no handoff artifact and no chunking. If you want every compaction to use the QOL bounded path, turn **Custom compaction summaries** on.
+
+Recommended values for autonomous/Flightdeck runs:
+
+- Keep **Long-session budget guard** on. Lower **Budget guard percent** to `75` if your provider buffers are tight.
+- Optionally turn **Custom compaction summaries** on so user-initiated and idle compactions also use the QOL chunked summarizer + handoff artifact. (Budget-guard-triggered compactions always use them regardless of this setting.)
+- Lower **Chunked compaction input cap** to ~`120000` when the summarizer model has a small context window.
+
 ### Thinking
 
 | Setting | What it does |

package/extensions/qol/budget-guard-runtime.ts

@@ -0,0 +1,100 @@
+// Runtime dispatch for the agent_end budget guard. Owns the last-crossing
+// key and in-flight flag so the guard fires exactly once per threshold
+// crossing, validates ctx.compact before marking in-flight, and clears the
+// crossing key on failure so the next agent_end can retry.
+
+import { QOL_BUDGET_GUARD_SENTINEL, type BudgetTrigger } from "./budget-guard.js";
+
+export type GuardLevel = "info" | "warning" | "error";
+
+export interface GuardCompactOptions {
+	customInstructions?: string;
+	onComplete?: (...args: unknown[]) => void;
+	onError?: (error: Error) => void;
+}
+
+export interface GuardDispatchInput {
+	trigger: BudgetTrigger | undefined;
+	compact: ((options: GuardCompactOptions) => void) | undefined;
+	notify: (message: string, level: GuardLevel) => void;
+	staleCtx?: () => boolean;
+}
+
+export type DispatchOutcome =
+	| { kind: "ignored" }
+	| { kind: "no-trigger" }
+	| { kind: "dedup" }
+	| { kind: "in-flight" }
+	| { kind: "no-compact-fn" }
+	| { kind: "dispatched"; reason: string }
+	| { kind: "dispatch-threw"; reason: string; error: string }
+	| { kind: "complete" }
+	| { kind: "failed"; error: string };
+
+export class BudgetGuardDriver {
+	private lastKey: string | undefined;
+	private inFlight = false;
+
+	reset(): void {
+		this.lastKey = undefined;
+		this.inFlight = false;
+	}
+
+	/** Returns true if the next call to dispatch is allowed to fire. Visible for tests. */
+	get canFire(): boolean {
+		return !this.inFlight;
+	}
+
+	get currentKey(): string | undefined {
+		return this.lastKey;
+	}
+
+	noteSessionCompacted(): void {
+		// Successful compaction drops usage below the budget; let the next
+		// crossing re-fire.
+		this.lastKey = undefined;
+		this.inFlight = false;
+	}
+
+	dispatch(input: GuardDispatchInput): DispatchOutcome {
+		if (input.staleCtx?.()) return { kind: "ignored" };
+		if (this.inFlight) return { kind: "in-flight" };
+		const trigger = input.trigger;
+		if (!trigger) {
+			this.lastKey = undefined;
+			return { kind: "no-trigger" };
+		}
+		if (trigger.key === this.lastKey) return { kind: "dedup" };
+		if (typeof input.compact !== "function") {
+			input.notify(`QOL budget guard cannot fire: ctx.compact is unavailable (${trigger.reason}).`, "warning");
+			return { kind: "no-compact-fn" };
+		}
+		input.notify(`QOL budget guard starting compaction: ${trigger.reason}`, "info");
+		this.inFlight = true;
+		this.lastKey = trigger.key;
+		const instructions = `${QOL_BUDGET_GUARD_SENTINEL} QOL budget guard triggered at agent_end because ${trigger.reason}. Bound the summary input, preserve current task state, decisions, files, blockers, and next steps.`;
+		try {
+			input.compact({
+				customInstructions: instructions,
+				onComplete: () => {
+					this.inFlight = false;
+					input.notify("QOL budget guard compaction completed.", "info");
+				},
+				onError: (error: Error) => {
+					this.inFlight = false;
+					// Allow the next agent_end to retry rather than poisoning the
+					// crossing key after a transient failure.
+					this.lastKey = undefined;
+					input.notify(`QOL budget guard compaction failed: ${error.message}`, "error");
+				},
+			});
+			return { kind: "dispatched", reason: trigger.reason };
+		} catch (error) {
+			this.inFlight = false;
+			this.lastKey = undefined;
+			const message = error instanceof Error ? error.message : String(error);
+			input.notify(`QOL budget guard compaction failed to start: ${message}`, "error");
+			return { kind: "dispatch-threw", error: message, reason: trigger.reason };
+		}
+	}
+}

package/extensions/qol/budget-guard.ts

@@ -0,0 +1,317 @@
+// Pure helpers for the long-session compaction budget guard. Kept dependency-free
+// so the chunking + risk math can be unit-tested without pulling the pi-ai or
+// pi-coding-agent peer deps. The wiring into the qol extension (settings reads,
+// session manager, ctx.compact) lives in compaction.ts and qol.ts.
+
+export interface BudgetTriggerInput {
+	enabled: boolean;
+	tokens: number;
+	contextWindow?: number;
+	tokenLimit: number;
+	percentLimit: number;
+}
+
+export interface BudgetTrigger {
+	reason: string;
+	key: string;
+	tokens: number;
+	contextWindow?: number;
+	percent?: number;
+}
+
+export function computeBudgetTrigger(input: BudgetTriggerInput): BudgetTrigger | undefined {
+	if (!input.enabled) return undefined;
+	if (!Number.isFinite(input.tokens) || input.tokens <= 0) return undefined;
+	const tokenLimit = Math.floor(input.tokenLimit);
+	if (tokenLimit > 0 && input.tokens >= tokenLimit) {
+		const bucket = Math.floor(input.tokens / Math.max(1, tokenLimit));
+		return {
+			contextWindow: input.contextWindow,
+			key: `tokens:${tokenLimit}:${bucket}`,
+			percent: input.contextWindow ? (input.tokens / input.contextWindow) * 100 : undefined,
+			reason: `${input.tokens.toLocaleString()} tokens >= ${tokenLimit.toLocaleString()} budget token limit`,
+			tokens: input.tokens,
+		};
+	}
+	const percentLimit = input.percentLimit;
+	if (percentLimit > 0 && input.contextWindow) {
+		const percent = (input.tokens / input.contextWindow) * 100;
+		if (percent >= percentLimit) {
+			const bucket = Math.floor(percent / Math.max(1, percentLimit));
+			return {
+				contextWindow: input.contextWindow,
+				key: `percent:${percentLimit}:${bucket}`,
+				percent,
+				reason: `${percent.toFixed(1)}% context >= ${percentLimit}% budget guard`,
+				tokens: input.tokens,
+			};
+		}
+	}
+	return undefined;
+}
+
+export function chunkConversationText(text: string, maxChars: number): string[] {
+	if (maxChars <= 0 || text.length <= maxChars) return [text];
+	const chunks: string[] = [];
+	const breaks = /\n{2,}/g;
+	let cursor = 0;
+	while (cursor < text.length) {
+		const remaining = text.length - cursor;
+		if (remaining <= maxChars) {
+			chunks.push(text.slice(cursor));
+			break;
+		}
+		const slice = text.slice(cursor, cursor + maxChars);
+		breaks.lastIndex = 0;
+		let breakAt = -1;
+		let match: RegExpExecArray | null;
+		// Pick the latest paragraph break inside the slice so chunks land on
+		// message boundaries. The half-slice floor avoids degenerate tiny chunks
+		// when the only paragraph break is right at the start of the window.
+		while ((match = breaks.exec(slice)) !== null) {
+			if (match.index >= Math.floor(maxChars / 2)) breakAt = match.index + match[0].length;
+		}
+		const end = breakAt > 0 ? cursor + breakAt : cursor + maxChars;
+		chunks.push(text.slice(cursor, end));
+		cursor = end;
+	}
+	return chunks;
+}
+
+export interface TranscriptRiskInput {
+	chars: number;
+	threshold: number;
+	messageCount: number;
+	error?: string;
+}
+
+export interface TranscriptRiskResult extends TranscriptRiskInput {
+	exceeded: boolean;
+}
+
+export function evaluateTranscriptRisk(input: TranscriptRiskInput): TranscriptRiskResult {
+	if (input.error) {
+		return { chars: 0, error: input.error, exceeded: false, messageCount: input.messageCount, threshold: input.threshold };
+	}
+	if (input.threshold <= 0 || input.messageCount <= 0 || input.chars <= 0) {
+		return { chars: input.chars, exceeded: false, messageCount: input.messageCount, threshold: input.threshold };
+	}
+	return {
+		chars: input.chars,
+		exceeded: input.chars >= input.threshold,
+		messageCount: input.messageCount,
+		threshold: input.threshold,
+	};
+}
+
+/**
+ * Sentinel marker injected into customInstructions when budget guard triggers
+ * a compaction. Detected by handleQolCompaction to force the bounded QOL path
+ * + handoff artifact write regardless of the global compaction.customEnabled
+ * setting.
+ */
+export const QOL_BUDGET_GUARD_SENTINEL = "[QOL_BUDGET_GUARD]";
+
+export function isBudgetGuardCompaction(customInstructions: unknown): boolean {
+	return typeof customInstructions === "string" && customInstructions.includes(QOL_BUDGET_GUARD_SENTINEL);
+}
+
+export interface SummarizeRequest {
+	text: string;
+	customInstructions?: string;
+	previousSummary?: string;
+	skipChunking: true;
+}
+
+export interface SummarizeOutcome {
+	model: string;
+	summary: string;
+	via: "model" | "remote";
+}
+
+export type SummarizeFn = (request: SummarizeRequest) => Promise<SummarizeOutcome>;
+
+export interface OrchestrateChunkedOptions {
+	text: string;
+	summarize: SummarizeFn;
+	maxInputChars: number;
+	signal?: AbortSignal;
+	customInstructions?: string;
+	previousSummary?: string;
+	notify?: (message: string, level?: "info" | "warning" | "error") => void;
+}
+
+export interface OrchestrateChunkedResult extends SummarizeOutcome {
+	chunkCount: number;
+	reduceLevels: number;
+	requestCount: number;
+}
+
+function instructionsForChunk(custom: string | undefined, index: number, total: number): string {
+	const base = `This is chunk ${index + 1} of ${total} from a long conversation. Preserve all concrete files, commands, decisions, blockers, and current tasks visible in this chunk so a follow-up summary-of-summaries pass can stitch the timeline together.`;
+	return custom?.trim() ? `${custom.trim()}\n\n${base}` : base;
+}
+
+function instructionsForReduce(custom: string | undefined, level: number, count: number): string {
+	const base = `Tree-reduce level ${level}: merge the following ${count} chunk summaries (oldest first) into a single continuation summary. De-duplicate facts, keep exact files/commands/paths, preserve decisions, blockers, current tasks, and any artifact paths. If chunks contradict, prefer the most recent.`;
+	return custom?.trim() ? `${custom.trim()}\n\n${base}` : base;
+}
+
+function partition(items: string[], maxChars: number, separator: string, minBatch: number = 1): string[][] {
+	const groups: string[][] = [];
+	let current: string[] = [];
+	let currentLen = 0;
+	const sepLen = separator.length;
+	for (const item of items) {
+		const projected = current.length === 0 ? item.length : currentLen + sepLen + item.length;
+		if (current.length >= minBatch && projected > maxChars) {
+			groups.push(current);
+			current = [item];
+			currentLen = item.length;
+		} else {
+			current.push(item);
+			currentLen = projected;
+		}
+	}
+	if (current.length > 0) groups.push(current);
+	return groups;
+}
+
+/**
+ * Bounded chunk + tree-reduce orchestrator. Every summarize() request gets
+ * a text body that is guaranteed to be <= maxInputChars (the chunker enforces
+ * the cap for source chunks; partition enforces it for reduce batches). When
+ * a reduce batch contains a single partial that's already over cap the
+ * orchestrator hard-truncates rather than retrying forever.
+ */
+export async function orchestrateChunkedSummary(options: OrchestrateChunkedOptions): Promise<OrchestrateChunkedResult> {
+	const { customInstructions, maxInputChars, notify, previousSummary, signal, summarize, text } = options;
+	if (maxInputChars <= 0 || text.length <= maxInputChars) {
+		if (signal?.aborted) throw new Error("Compaction aborted");
+		const single = await summarize({
+			customInstructions,
+			previousSummary,
+			skipChunking: true,
+			text,
+		});
+		return { ...single, chunkCount: 1, reduceLevels: 0, requestCount: 1 };
+	}
+	const chunks = chunkConversationText(text, maxInputChars);
+	notify?.(`QOL chunked compaction: summarizing ${chunks.length} chunk(s) (input ${text.length.toLocaleString()} chars > ${maxInputChars.toLocaleString()} cap).`, "info");
+	let requestCount = 0;
+	const partials: string[] = [];
+	let lastVia: "model" | "remote" = "model";
+	let lastModel = "";
+	let previous = previousSummary;
+	for (let i = 0; i < chunks.length; i += 1) {
+		if (signal?.aborted) throw new Error("Compaction aborted");
+		const chunk = chunks[i] ?? "";
+		const partial = await summarize({
+			customInstructions: instructionsForChunk(customInstructions, i, chunks.length),
+			previousSummary: previous,
+			skipChunking: true,
+			text: chunk,
+		});
+		requestCount += 1;
+		if (!partial.summary.trim()) throw new Error(`Chunk ${i + 1}/${chunks.length} summary was empty`);
+		partials.push(`### Chunk ${i + 1}/${chunks.length}\n${partial.summary.trim()}`);
+		previous = partial.summary;
+		lastVia = partial.via;
+		lastModel = partial.model;
+	}
+
+	let level = partials;
+	let reduceLevels = 0;
+	const separator = "\n\n";
+	const MAX_REDUCE_LEVELS = 12;
+	while (true) {
+		const combined = level.join(separator);
+		if (combined.length <= maxInputChars) {
+			if (signal?.aborted) throw new Error("Compaction aborted");
+			const final = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels + 1, level.length),
+				previousSummary,
+				skipChunking: true,
+				text: combined,
+			});
+			requestCount += 1;
+			if (!final.summary.trim()) throw new Error("Final reduce summary was empty");
+			return {
+				chunkCount: chunks.length,
+				model: final.model || lastModel,
+				reduceLevels: reduceLevels + 1,
+				requestCount,
+				summary: final.summary,
+				via: final.via || lastVia,
+			};
+		}
+		reduceLevels += 1;
+		if (reduceLevels > MAX_REDUCE_LEVELS) {
+			// Defensive: refuse to spin forever if a model keeps emitting
+			// summaries larger than the cap. Final summarize over the
+			// hard-truncated joined level returns a bounded answer.
+			const truncated = combined.slice(0, maxInputChars);
+			const final = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels, level.length),
+				previousSummary,
+				skipChunking: true,
+				text: truncated,
+			});
+			requestCount += 1;
+			return {
+				chunkCount: chunks.length,
+				model: final.model || lastModel,
+				reduceLevels,
+				requestCount,
+				summary: final.summary,
+				via: final.via || lastVia,
+			};
+		}
+		// Force-pair: at level >1 every batch must contain >=2 items so we
+		// always make progress. The summarize() call gets a text that may
+		// exceed the cap when each partial is itself near-cap; truncate to
+		// cap so the request remains bounded.
+		const minBatch = 2;
+		const batches = partition(level, maxInputChars, separator, minBatch);
+		const nextLevel: string[] = [];
+		for (const batch of batches) {
+			if (signal?.aborted) throw new Error("Compaction aborted");
+			if (batch.length === 1) {
+				const only = batch[0] ?? "";
+				nextLevel.push(only.length > maxInputChars ? only.slice(0, maxInputChars) : only);
+				continue;
+			}
+			let batchText = batch.join(separator);
+			if (batchText.length > maxInputChars) batchText = batchText.slice(0, maxInputChars);
+			const summary = await summarize({
+				customInstructions: instructionsForReduce(customInstructions, reduceLevels, batch.length),
+				previousSummary,
+				skipChunking: true,
+				text: batchText,
+			});
+			requestCount += 1;
+			if (!summary.summary.trim()) throw new Error(`Tree-reduce level ${reduceLevels} batch summary was empty`);
+			nextLevel.push(summary.summary);
+			lastVia = summary.via;
+			lastModel = summary.model;
+		}
+		if (nextLevel.length === 0) throw new Error("Tree-reduce collapsed to empty level");
+		if (nextLevel.length >= level.length) {
+			// No progress this round — fall back to hard truncation on the next
+			// pass via the level-cap guard. This typically means the model is
+			// emitting near-cap summaries; the MAX_REDUCE_LEVELS guard above
+			// will eventually terminate the loop with a truncated final.
+		}
+		level = nextLevel;
+		if (level.length === 1 && level[0]!.length <= maxInputChars) {
+			return {
+				chunkCount: chunks.length,
+				model: lastModel,
+				reduceLevels,
+				requestCount,
+				summary: level[0]!,
+				via: lastVia,
+			};
+		}
+	}
+}