@hank-warren/pi-statusline 0.1.1 → 0.1.3

package/README.md

@@ -10,12 +10,30 @@ gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m
 
 ## What it shows
 
-- **Line 1** — active model ID, current directory basename and Git branch, and current context usage/window. A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate.
+- **Line 1** — active model ID, current directory basename and Git branch, and current context usage/window. A yellow `*` marks a dirty checkout and `⇣N` shows how many commits it is behind its locally known upstream ref. Unknown context usage is rendered as `?/<window>` until Pi can provide an estimate. Exceptional prompt-cache hits trigger the celebration described below.
 - **Worktree lines** — when the session works in or sends tool calls into linked worktrees, one line shows the same branch/dirty/behind state for each worktree plus its associated PR number.
 - **Final line** — the full Pi session ID.
 
 It uses a fixed true-color palette with context warning thresholds.
 
+## Neon cache-wave celebration
+
+Whenever one assistant response reaches a prompt-cache hit rate of at least 90%, a temporary module is appended after context usage for about two seconds:
+
+```text
+gpt-5.6-sol | pi-extensions:main | 135k/272k | ⚡ 96% CACHE
+```
+
+Only the `⚡ 96% CACHE` badge animates with a cyan → blue → magenta wave every 80 ms. The existing model, repository, context, separators, worktree, and session-ID rendering do not change.
+
+The rate is evaluated per provider response as:
+
+```text
+cacheRead / (input + cacheRead + cacheWrite)
+```
+
+Output and reasoning tokens are excluded because they are not prompt-cache candidates. A zero-token denominator does not trigger the effect, exactly 90% does, and only the displayed percentage is rounded. Another qualifying response during the animation restarts it from frame zero with the new percentage. After expiry, the original statusline is restored exactly.
+
 ## Worktree/PR tracking behavior
 
 - Only worktrees touched on the active Pi session branch are included.
@@ -30,7 +48,9 @@ PR lookups use the `gh` CLI when available and degrade gracefully without it.
 
 Pi's fullscreen renderer only re-emits terminal rows whose rendered content changed. The worktree and session-ID lines are static for the life of a session, so if their cells ever desync from Pi's row cache — stale transcript text, a process sharing the tty, a stray escape sequence — nothing repaints them and the artifact persists.
 
-To repair that, the extension asks Pi for a forced full redraw at turn boundaries and on a 30-second idle sweep, throttled to at most one every five seconds. Both are skipped entirely in regular TUI mode, which reprints its whole block each frame and therefore self-heals. A forced redraw drops a scrollback text selection highlight for a single frame.
+To repair that promptly without repeatedly clearing the screen, a one-second sweep changes an invisible marker on the fullscreen footer and requests a targeted differential render. Only the statusline rows compare as changed, so they repaint at most once per second even while the rest of Pi is actively rendering. A 30-second forced full redraw remains as a fallback for corruption outside the footer, throttled to at most one every five seconds and also requested at turn boundaries.
+
+Both repair layers are skipped entirely in regular TUI mode, which reprints its whole block each frame and therefore self-heals. Only the slower forced fallback can drop a scrollback text selection highlight for a single frame.
 
 ## Install
 

package/cache-celebration.ts

@@ -0,0 +1,132 @@
+export const CACHE_HIT_THRESHOLD = 0.9;
+export const CACHE_CELEBRATION_FRAME_INTERVAL_MS = 80;
+export const CACHE_CELEBRATION_DURATION_MS = 2_000;
+
+export interface CacheUsage {
+	input: number;
+	cacheRead: number;
+	cacheWrite: number;
+}
+
+export interface CacheCelebrationSnapshot {
+	percent: number;
+	frame: number;
+}
+
+export interface CacheCelebrationTarget {
+	start(percent: number): void;
+}
+
+export interface CacheCelebrationControllerOptions {
+	frameIntervalMs?: number;
+	durationMs?: number;
+	now?: () => number;
+	schedule?: (callback: () => void, intervalMs: number) => unknown;
+	cancel?: (handle: unknown) => void;
+}
+
+function defaultSchedule(callback: () => void, intervalMs: number): unknown {
+	const timer = setInterval(callback, intervalMs);
+	// A cosmetic celebration must never keep Pi alive.
+	(timer as { unref?: () => void }).unref?.();
+	return timer;
+}
+
+function defaultCancel(handle: unknown): void {
+	clearInterval(handle as ReturnType<typeof setInterval>);
+}
+
+/** Return the prompt-cache hit ratio for one response, or null without prompt tokens. */
+export function cacheReadHitRate(usage: CacheUsage): number | null {
+	const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+	return promptTokens > 0 ? usage.cacheRead / promptTokens : null;
+}
+
+/** Return the rounded badge percentage only when a response qualifies for celebration. */
+export function qualifyingCacheHitPercent(usage: CacheUsage): number | null {
+	const rate = cacheReadHitRate(usage);
+	return rate !== null && rate >= CACHE_HIT_THRESHOLD ? Math.round(rate * 100) : null;
+}
+
+/**
+ * Apply the same narrowing used by the turn_end hook and start a celebration
+ * for a qualifying assistant response.
+ */
+export function triggerCacheCelebrationForMessage(
+	message: unknown,
+	target: CacheCelebrationTarget,
+): boolean {
+	if (!message || typeof message !== "object") return false;
+	const candidate = message as { role?: unknown; usage?: Partial<CacheUsage> };
+	if (candidate.role !== "assistant" || !candidate.usage) return false;
+	const { input, cacheRead, cacheWrite } = candidate.usage;
+	if (typeof input !== "number" || typeof cacheRead !== "number" || typeof cacheWrite !== "number") {
+		return false;
+	}
+	const percent = qualifyingCacheHitPercent({ input, cacheRead, cacheWrite });
+	if (percent === null) return false;
+	target.start(percent);
+	return true;
+}
+
+/** Owns the short-lived animation timer and exposes an immutable render snapshot. */
+export class CacheCelebrationController implements CacheCelebrationTarget {
+	private current: CacheCelebrationSnapshot | undefined;
+	private startedAt = 0;
+	private timerHandle: unknown;
+	private readonly frameIntervalMs: number;
+	private readonly durationMs: number;
+	private readonly now: () => number;
+	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+
+	constructor(
+		private readonly requestRender: () => void,
+		options: CacheCelebrationControllerOptions = {},
+	) {
+		this.frameIntervalMs = options.frameIntervalMs ?? CACHE_CELEBRATION_FRAME_INTERVAL_MS;
+		this.durationMs = options.durationMs ?? CACHE_CELEBRATION_DURATION_MS;
+		this.now = options.now ?? Date.now;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.cancel = options.cancel ?? defaultCancel;
+	}
+
+	start(percent: number): void {
+		this.clearTimer();
+		this.startedAt = this.now();
+		this.current = { percent, frame: 0 };
+		this.requestRender();
+		this.timerHandle = this.schedule(() => this.tick(), this.frameIntervalMs);
+	}
+
+	snapshot(): CacheCelebrationSnapshot | undefined {
+		return this.current ? { ...this.current } : undefined;
+	}
+
+	/** Stop without requesting a render; intended for footer/session teardown. */
+	dispose(): void {
+		this.clearTimer();
+		this.current = undefined;
+	}
+
+	private tick(): void {
+		if (!this.current) return;
+		const elapsed = this.now() - this.startedAt;
+		if (elapsed >= this.durationMs) {
+			this.clearTimer();
+			this.current = undefined;
+			this.requestRender();
+			return;
+		}
+		this.current = {
+			...this.current,
+			frame: Math.floor(elapsed / this.frameIntervalMs),
+		};
+		this.requestRender();
+	}
+
+	private clearTimer(): void {
+		if (this.timerHandle !== undefined) this.cancel(this.timerHandle);
+		this.timerHandle = undefined;
+	}
+}

package/index.ts

@@ -1,6 +1,11 @@
 import { basename } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
+import {
+	CacheCelebrationController,
+	type CacheCelebrationSnapshot,
+	triggerCacheCelebrationForMessage,
+} from "./cache-celebration.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
 import {
 	type GitRepositoryStatus,
@@ -18,6 +23,7 @@ export interface StatuslineData {
 	contextWindow: number;
 	worktrees: SessionWorktree[];
 	sessionId: string;
+	cacheCelebration?: CacheCelebrationSnapshot;
 }
 
 const BLUE = "\x1b[38;2;0;153;255m";
@@ -28,8 +34,13 @@ const RED = "\x1b[38;2;255;85;85m";
 const YELLOW = "\x1b[38;2;230;200;0m";
 const WHITE = "\x1b[38;2;220;220;220m";
 const MAGENTA = "\x1b[38;2;190;120;255m";
+const NEON_CYAN = "\x1b[38;2;0;255;255m";
+const NEON_BLUE = "\x1b[38;2;0;125;255m";
+const NEON_MAGENTA = "\x1b[38;2;255;0;255m";
 const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
+const NEON_WAVE = [NEON_CYAN, NEON_CYAN, NEON_BLUE, NEON_BLUE, NEON_MAGENTA, NEON_MAGENTA] as const;
 
 function styled(style: string, text: string): string {
 	return `${style}${text}${RESET}`;
@@ -62,6 +73,20 @@ function renderRepository(name: string, status: GitRepositoryStatus, nameColor =
 	return part;
 }
 
+export function renderCacheCelebrationLine(
+	summary: string,
+	celebration: CacheCelebrationSnapshot,
+): string {
+	const badge = `⚡ ${celebration.percent}% CACHE`;
+	const animatedBadge = Array.from(badge)
+		.map((character, index) => {
+			const color = NEON_WAVE[(index + celebration.frame) % NEON_WAVE.length];
+			return `${BOLD}${color}${character}${RESET}`;
+		})
+		.join("");
+	return `${summary}${styled(DIM, " | ")}${animatedBadge}`;
+}
+
 function renderWorktreeLine(worktrees: SessionWorktree[]): string {
 	const separator = styled(DIM, " | ");
 	const parts = worktrees.map((worktree) => {
@@ -88,8 +113,11 @@ export function renderStatusline(data: StatuslineData, width: number): string[]
 	const context = `${used}${styled(DIM, "/")}${styled(WHITE, formatTokenCount(data.contextWindow))}`;
 	const cwd = data.cwdGit ? renderRepository(data.cwd, data.cwdGit) : styled(CYAN, data.cwd);
 	const summary = styled(BLUE, data.model) + separator + cwd + separator + context;
+	const firstLine = data.cacheCelebration
+		? renderCacheCelebrationLine(summary, data.cacheCelebration)
+		: summary;
 
-	const lines = [truncateToWidth(summary, width)];
+	const lines = [truncateToWidth(firstLine, width)];
 	if (data.worktrees.length > 0) lines.push(truncateToWidth(renderWorktreeLine(data.worktrees), width, "…"));
 	lines.push(truncateToWidth(styled(DIM, data.sessionId), width));
 	return lines;
@@ -98,6 +126,7 @@ export function renderStatusline(data: StatuslineData, width: number): string[]
 export default function statuslineExtension(pi: ExtensionAPI): void {
 	let requestRender: (() => void) | undefined;
 	const fullRedraw = new FullRedrawScheduler();
+	const cacheCelebration = new CacheCelebrationController(() => requestRender?.());
 	let tracker: SessionWorktreeTracker | undefined;
 	let cwdGit: GitRepositoryStatus | null = null;
 	let cwdStatusAbort: AbortController | undefined;
@@ -154,6 +183,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	};
 
 	pi.on("session_start", (_event, ctx) => {
+		cacheCelebration.dispose();
 		if (ctx.mode !== "tui") return;
 
 		ctx.ui.setFooter((tui, _theme, footerData) => {
@@ -169,6 +199,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			return {
 				dispose(): void {
 					stopBranchUpdates();
+					cacheCelebration.dispose();
 					fullRedraw.detach();
 					requestRender = undefined;
 				},
@@ -178,17 +209,20 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					const cwd = basename(ctx.cwd) || ctx.cwd;
 					const model = ctx.model?.id.split("/").pop() || "no-model";
 
-					return renderStatusline(
-						{
-							model,
-							cwd,
-							cwdGit,
-							contextTokens: usage?.tokens ?? null,
-							contextWindow: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
-							worktrees: tracker?.getWorktrees() ?? [],
-							sessionId: ctx.sessionManager.getSessionId(),
-						},
-						width,
+					return fullRedraw.decorate(
+						renderStatusline(
+							{
+								model,
+								cwd,
+								cwdGit,
+								contextTokens: usage?.tokens ?? null,
+								contextWindow: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
+								worktrees: tracker?.getWorktrees() ?? [],
+								sessionId: ctx.sessionManager.getSessionId(),
+								cacheCelebration: cacheCelebration.snapshot(),
+							},
+							width,
+						),
 					);
 				},
 			};
@@ -200,7 +234,8 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	pi.on("tool_call", (event) => {
 		if (tracker) runInBackground(tracker.observeToolInput(event.toolName, event.input));
 	});
-	pi.on("turn_end", (_event, ctx) => {
+	pi.on("turn_end", (event, ctx) => {
+		if (requestRender) triggerCacheCelebrationForMessage(event.message, cacheCelebration);
 		fullRedraw.request();
 		requestRender?.();
 		runInBackground(refreshCwdStatus(ctx));
@@ -209,6 +244,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 	pi.on("model_select", () => requestRender?.());
 	pi.on("session_tree", (_event, ctx) => resetTracker(ctx));
 	pi.on("session_shutdown", () => {
+		cacheCelebration.dispose();
 		fullRedraw.detach();
 		tracker?.dispose();
 		tracker = undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.1.1",
-  "description": "Compact Pi footer statusline: model ID, git branch/dirty/behind state, linked worktrees with PR numbers, context usage, and session ID.",
+  "version": "0.1.3",
+  "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -32,6 +32,7 @@
   },
   "files": [
     "index.ts",
+    "cache-celebration.ts",
     "redraw.ts",
     "worktrees.ts",
     "README.md",

package/redraw.ts

@@ -3,24 +3,30 @@
  *
  * Pi's fullscreen (alt-screen) renderer writes rows differentially: a row whose
  * rendered content is byte-identical to the previous frame is never re-emitted.
- * That is normally invisible, but this statusline is the only thing on screen
- * with permanently static rows — the worktree line barely changes and the
- * session id never changes at all. Once those terminal cells desync from Pi's
- * row cache (stale transcript text, a process sharing the tty, a stray escape
- * sequence), nothing repaints them and the garbage persists for the whole
- * session.
+ * Once terminal cells desync from Pi's row cache, static statusline rows can
+ * therefore retain stale text indefinitely.
  *
- * `requestRender(true)` resets the renderer's row cache and repaints every row,
- * which repairs the damage. It is heavier than a normal frame, so this
- * scheduler keeps forced redraws rare: fullscreen only, throttled to a minimum
- * gap, driven by turn boundaries plus a slow idle sweep.
+ * This scheduler repairs the footer in two layers:
+ *
+ * 1. A short timer alternates between two visually equivalent ANSI reset
+ *    prefixes and requests a normal render. Only the statusline rows compare as
+ *    changed, even when Pi is otherwise idle.
+ * 2. `request()` keeps the slower forced full redraw fallback for corruption
+ *    outside the footer.
+ *
+ * Both layers are fullscreen-only. Regular mode already reprints its block and
+ * does not need a periodic render.
  */
 
 /** Minimum spacing between forced full redraws. */
 export const DEFAULT_MIN_GAP_MS = 5_000;
-/** Idle cadence so artifacts also heal without any agent activity. */
+/** Idle cadence for targeted statusline-row repainting. */
+export const DEFAULT_ROW_REFRESH_INTERVAL_MS = 1_000;
+/** Slow fallback cadence for corruption outside the footer. */
 export const DEFAULT_IDLE_INTERVAL_MS = 30_000;
 
+const ANSI_RESET = "\x1b[0m";
+
 /** The subset of Pi's TUI surface this scheduler needs. */
 export interface RedrawTarget {
 	readonly mode: string;
@@ -29,6 +35,7 @@ export interface RedrawTarget {
 
 export interface FullRedrawSchedulerOptions {
 	minGapMs?: number;
+	rowRefreshIntervalMs?: number;
 	idleIntervalMs?: number;
 	now?: () => number;
 	schedule?: (callback: () => void, intervalMs: number) => unknown;
@@ -48,9 +55,12 @@ function defaultCancel(handle: unknown): void {
 
 export class FullRedrawScheduler {
 	private target: RedrawTarget | undefined;
-	private handle: unknown;
+	private rowRefreshHandle: unknown;
+	private fullRedrawHandle: unknown;
 	private lastRedrawAt = Number.NEGATIVE_INFINITY;
+	private decorationPhase = 0;
 	private readonly minGapMs: number;
+	private readonly rowRefreshIntervalMs: number;
 	private readonly idleIntervalMs: number;
 	private readonly now: () => number;
 	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
@@ -58,34 +68,65 @@ export class FullRedrawScheduler {
 
 	constructor(options: FullRedrawSchedulerOptions = {}) {
 		this.minGapMs = options.minGapMs ?? DEFAULT_MIN_GAP_MS;
+		this.rowRefreshIntervalMs = options.rowRefreshIntervalMs ?? DEFAULT_ROW_REFRESH_INTERVAL_MS;
 		this.idleIntervalMs = options.idleIntervalMs ?? DEFAULT_IDLE_INTERVAL_MS;
 		this.now = options.now ?? Date.now;
 		this.schedule = options.schedule ?? defaultSchedule;
 		this.cancel = options.cancel ?? defaultCancel;
 	}
 
-	/** Bind to the TUI that owns the footer and start the idle sweep. */
+	/** Bind to the TUI that owns the footer and start both repair sweeps. */
 	attach(target: RedrawTarget): void {
 		this.detach();
 		this.target = target;
-		this.handle = this.schedule(() => {
+		this.lastRedrawAt = Number.NEGATIVE_INFINITY;
+		this.decorationPhase = 0;
+		this.rowRefreshHandle = this.schedule(() => {
+			this.requestRowRefresh();
+		}, this.rowRefreshIntervalMs);
+		this.fullRedrawHandle = this.schedule(() => {
 			this.request();
 		}, this.idleIntervalMs);
 	}
 
 	detach(): void {
-		if (this.handle !== undefined) this.cancel(this.handle);
-		this.handle = undefined;
+		if (this.rowRefreshHandle !== undefined) this.cancel(this.rowRefreshHandle);
+		if (this.fullRedrawHandle !== undefined) this.cancel(this.fullRedrawHandle);
+		this.rowRefreshHandle = undefined;
+		this.fullRedrawHandle = undefined;
 		this.target = undefined;
 	}
 
+	/**
+	 * Make footer rows byte-different without changing their visible contents.
+	 * Pi will then clear and repaint those rows during an ordinary differential
+	 * render instead of requiring a full-screen clear.
+	 */
+	decorate(lines: string[]): string[] {
+		if (this.target?.mode !== "fullscreen") return lines;
+		const prefix = this.decorationPhase === 0 ? ANSI_RESET : `${ANSI_RESET}${ANSI_RESET}`;
+		return lines.map((line) => `${prefix}${line}`);
+	}
+
+	/**
+	 * Advance the invisible footer marker and request an ordinary render. The
+	 * timer calls this at most once per interval, so active Pi frames do not
+	 * repeatedly repaint otherwise-static statusline rows.
+	 */
+	requestRowRefresh(): boolean {
+		const target = this.target;
+		if (!target || target.mode !== "fullscreen") return false;
+		this.decorationPhase = (this.decorationPhase + 1) % 2;
+		target.requestRender();
+		return true;
+	}
+
 	/**
 	 * Ask for a forced full redraw. No-ops outside fullscreen mode and while
 	 * throttled. Returns whether a redraw was actually requested.
 	 */
 	request(): boolean {
 		const target = this.target;
-		// Regular mode reprints its whole block every frame, so it self-heals.
 		if (!target || target.mode !== "fullscreen") return false;
 		const now = this.now();
 		if (now - this.lastRedrawAt < this.minGapMs) return false;