@underactive/pi-topping-statusline 0.2.8 → 0.3.0

package/src/token-rate.ts

@@ -3,9 +3,8 @@
  *
  * Upstream oh-my-pi computes the badge from the last assistant message's
  * usage.output / duration, but pi only reports usage at message end, so a
- * live rate needs an estimator. The pipeline (StreamingWordCounter + EMA
- * tracker + hold/fade lifecycle) is copied from pi-topping (same author,
- * ../pi-topping/src/{format,activity-meter,session}.ts):
+ * live rate needs an estimator. The pipeline (word counter, EMA tracker and
+ * hold/fade lifecycle) comes from @underactive/pi-topping-primitives/activity:
  *
  * - text/thinking deltas are counted as approximate tokens (word boundaries);
  * - an EMA (alpha 0.4) smooths 100ms samples into a rate;
@@ -15,6 +14,7 @@
  * The segment itself never disappears: idle renders as `--- tok/s`.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { RateHoldFade, StreamingWordCounter } from "@underactive/pi-topping-primitives/activity";
 import { FADE_SHADE_COUNT } from "./theme.js";
 import type { TokenRateDisplay } from "./types.js";
 
@@ -23,48 +23,6 @@ const SAMPLE_INTERVAL_MS = 100;
 const HOLD_MS = 1_500;
 /** pi-topping fades in 250ms; here the fade is stretched to 0.5s. */
 const FADE_MS = 500;
-const EMA_ALPHA = 0.4;
-
-/** Incremental whitespace-boundary word counter (pi-topping StreamingWordCounter). */
-class StreamingWordCounter {
-	#inWordByStream = new Map<string, boolean>();
-
-	count(text: string, stream: string): number {
-		let inWord = this.#inWordByStream.get(stream) ?? false;
-		let count = 0;
-		for (let i = 0; i < text.length; i++) {
-			const code = text.charCodeAt(i);
-			if (isWhitespace(code)) {
-				inWord = false;
-			} else if (!inWord) {
-				count++;
-				inWord = true;
-			}
-		}
-		this.#inWordByStream.set(stream, inWord);
-		return count;
-	}
-
-	reset(): void {
-		this.#inWordByStream.clear();
-	}
-}
-
-function isWhitespace(code: number): boolean {
-	return (
-		code === 32 ||
-		(code >= 9 && code <= 13) ||
-		code === 160 ||
-		code === 0x1680 ||
-		(code >= 0x2000 && code <= 0x200a) ||
-		code === 0x2028 ||
-		code === 0x2029 ||
-		code === 0x202f ||
-		code === 0x205f ||
-		code === 0x3000 ||
-		code === 0xfeff
-	);
-}
 
 export class TokenRateMonitor {
 	#requestRender: () => void;
@@ -77,18 +35,13 @@ export class TokenRateMonitor {
 	#liveTokens = 0;
 	#counter = new StreamingWordCounter();
 
-	// EMA tracker state (pi-topping TokRateTracker).
-	#emaRate = 0;
-	#emaLastTotal = 0;
-	#emaLastTime = 0;
-	#emaHasSample = false;
-	#emaPendingTokens = 0;
-
-	// Hold/fade lifecycle (pi-topping session.ts tick).
-	#lastSampledAt = 0;
-	#lastSampleTotal = 0;
-	#heldRate: number | null = null;
-	#fadeStartsAt = 0;
+	// EMA tracker plus hold/fade lifecycle.
+	#rate = new RateHoldFade({
+		holdMs: HOLD_MS,
+		fadeMs: FADE_MS,
+		shadeCount: FADE_SHADE_COUNT,
+		sampleIntervalMs: SAMPLE_INTERVAL_MS,
+	});
 	#lastRendered: TokenRateDisplay | undefined;
 
 	constructor(requestRender: () => void) {
@@ -125,9 +78,7 @@ export class TokenRateMonitor {
 			if (exact !== undefined) {
 				// Reconciliation resets the EMA at message boundaries; the held rate
 				// bridges the gap until fresh samples rebuild it.
-				this.#resetEma();
-				this.#lastSampledAt = 0;
-				this.#lastSampleTotal = this.#confirmTokens;
+				this.#rate.resetSampling(this.#confirmTokens);
 			}
 			this.#liveTokens = 0;
 			this.#counter.reset();
@@ -148,75 +99,23 @@ export class TokenRateMonitor {
 
 	/** Pure snapshot for the segment render; safe to call on any frame. */
 	getDisplay(now = Date.now()): TokenRateDisplay {
-		if (this.#heldRate !== null && now < this.#fadeStartsAt) {
-			return { rate: this.#heldRate, phase: "active", fadeShade: 0 };
-		}
-		if (this.#heldRate !== null && now < this.#fadeStartsAt + FADE_MS) {
-			const shade = Math.floor((now - this.#fadeStartsAt) / (FADE_MS / FADE_SHADE_COUNT));
-			return { rate: this.#heldRate, phase: "fading", fadeShade: shade };
-		}
-		return { rate: null, phase: "idle", fadeShade: 0 };
+		return this.#rate.display(now);
 	}
 
 	#resetTurn(): void {
 		this.#confirmTokens = 0;
 		this.#liveTokens = 0;
 		this.#counter.reset();
-		this.#resetEma();
-		this.#lastSampledAt = 0;
-		this.#lastSampleTotal = 0;
-		this.#heldRate = null;
-		this.#fadeStartsAt = 0;
-	}
-
-	#resetEma(): void {
-		this.#emaRate = 0;
-		this.#emaLastTotal = 0;
-		this.#emaLastTime = 0;
-		this.#emaHasSample = false;
-		this.#emaPendingTokens = 0;
-	}
-
-	#sampleEma(total: number, now: number): void {
-		if (!this.#emaHasSample) {
-			this.#emaLastTotal = total;
-			this.#emaHasSample = true;
-			this.#emaLastTime = now;
-			return;
-		}
-		const elapsedSeconds = (now - this.#emaLastTime) / 1_000;
-		if (elapsedSeconds <= 0) {
-			this.#emaPendingTokens += Math.max(0, total - this.#emaLastTotal);
-			this.#emaLastTotal = total;
-			return;
-		}
-		const totalDelta = this.#emaPendingTokens + Math.max(0, total - this.#emaLastTotal);
-		const instantRate = totalDelta / elapsedSeconds;
-		this.#emaRate = EMA_ALPHA * instantRate + (1 - EMA_ALPHA) * this.#emaRate;
-		this.#emaLastTotal = total;
-		this.#emaLastTime = now;
-		this.#emaPendingTokens = 0;
+		this.#rate.reset();
 	}
 
 	#tick(): void {
 		const now = Date.now();
-		if (this.#busy && now - this.#lastSampledAt >= SAMPLE_INTERVAL_MS) {
-			const total = this.#confirmTokens + this.#liveTokens;
-			// Do not reset the fade for an EMA-only decay while output is quiet.
-			const hasNewTokens = total > this.#lastSampleTotal;
-			this.#lastSampleTotal = total;
-			this.#sampleEma(total, now);
-			this.#lastSampledAt = now;
-			const rounded = Math.round(this.#emaRate);
-			if (rounded > 0 && hasNewTokens) {
-				this.#heldRate = rounded;
-				this.#fadeStartsAt = now + HOLD_MS;
-			}
-		}
-		if (!this.#busy && now >= this.#fadeStartsAt + FADE_MS) {
+		if (this.#busy) this.#rate.sample(this.#confirmTokens + this.#liveTokens, now);
+		const display = this.getDisplay(now);
+		if (!this.#busy && display.phase === "idle") {
 			this.#stopTimer();
 		}
-		const display = this.getDisplay(now);
 		if (
 			!this.#lastRendered ||
 			display.rate !== this.#lastRendered.rate ||

package/src/types.ts

@@ -17,6 +17,7 @@ export type StatusLineSegmentId =
 	| "pi_stats"
 	| "token_rate"
 	| "feeds"
+	| "cache_hit_graph"
 	| "context_graph"
 	| "scroll_hint"
 	| "working"
@@ -25,8 +26,8 @@ export type StatusLineSegmentId =
 
 /**
  * A feed the statusline subscribes to: custom session entries published by
- * another extension under `customType`, as pi-prompt-cache does with
- * "pi-prompt-cache/savings". `field` names the property of the entry's data
+ * another extension under `customType`, for example
+ * `pi.appendEntry("my-extension/savings", { savedUsd })`. `field` names the property of the entry's data
  * object to display, and `prefix` is the literal label drawn before it.
  */
 export interface StatusLineFeed {
@@ -37,9 +38,9 @@ export interface StatusLineFeed {
 }
 
 /**
- * currency keeps the rules pi-prompt-cache's author specified for the savings
- * figure: a signed half-cent floor so this segment and that extension's own
- * footer never disagree, two decimals below $100 and whole dollars above.
+ * currency keeps the rules specified for the savings figure this format was written
+ * for (published by pi-topping-compact, a private extension): a signed half-cent
+ * floor, two decimals below $100 and whole dollars above.
  */
 export type FeedFormat = "currency" | "number" | "text";
 
@@ -58,6 +59,7 @@ export interface StatusLineSegmentToggles {
 	feeds?: boolean;
 	feedsBottomLeft?: boolean;
 	tokenRateBottomLeft?: boolean;
+	cacheHitBar?: boolean;
 	contextBar?: boolean;
 	contextStats?: boolean;
 	scrollHint?: boolean;
@@ -84,6 +86,8 @@ export interface StatusLineSettings {
 	embedWorkingStatus?: boolean;
 	/** Host compaction progress in the bottom bar while pi compacts. */
 	embedCompactionProgress?: boolean;
+	/** Length of the cache hit bar in segments (3–10, default 4); the bar is logarithmic at every size. */
+	cacheHitBarSegments?: number;
 }
 
 /** Resolved per-segment render options; resolveEffectiveSettings always fills them. */
@@ -91,6 +95,7 @@ export interface StatusLineSegmentOptions {
 	model: { showModel: boolean; showProvider: boolean; showThinking: boolean };
 	path: { abbreviate: boolean; maxLength: number; stripWorkPrefix: boolean };
 	context: { showBar: boolean; showStats: boolean };
+	cacheHit: { cells: number };
 	/** Subscriptions rendered by the feeds segment, in display order. */
 	feeds: StatusLineFeed[];
 }
@@ -101,6 +106,8 @@ export interface SegmentIncludes {
 	pr: boolean;
 	piStats: boolean;
 	tokenRate: boolean;
+	/** Whether the cache-hit graph needs a session-usage snapshot. */
+	cacheHit: boolean;
 	feeds: readonly string[];
 }
 
@@ -137,6 +144,8 @@ export interface SegmentContext {
 	contextPercent: number | null;
 	contextTokens: number;
 	contextWindow: number;
+	/** The latest assistant response's cache-read share of its prompt tokens (pi's footer CH), or null when none has reported prompt tokens. */
+	cacheHitPercent?: number | null;
 	/**
 	 * True while contextPercent and contextTokens are pi's estimate of a freshly
 	 * compacted context, shown until pi measures the next response.

package/src/utils.ts

@@ -4,10 +4,11 @@
  * session-color.ts, tools/render-utils.ts, modes/shared.ts). Bun.color is
  * replaced with local hex math so this runs under any pi runtime.
  */
-import { stripVTControlCharacters } from "node:util";
-import { sliceByColumn, visibleWidth } from "@earendil-works/pi-tui";
-import { parseHex } from "./theme.js";
-import { hslToRgb, rgbToHex } from "./rainbow.js";
+import { colorToHex, rgbColor, sliceByColumn, visibleWidth } from "@earendil-works/pi-tui";
+import { hslToRgb, parseHex } from "@underactive/pi-topping-primitives/color";
+import { sanitizeLabel } from "@underactive/pi-topping-primitives/text";
+
+export { sanitizeLabel };
 
 export function formatNumber(n: number): string {
 	if (n < 1_000) return n.toString();
@@ -25,8 +26,8 @@ export function formatNumber(n: number): string {
 	return `${Math.round(n / 1_000_000_000)}B`;
 }
 
-export function shortenPath(filePath: string, homeDir?: string): string {
-	const home = homeDir ?? process.env.HOME ?? "";
+export function shortenPath(filePath: string): string {
+	const home = process.env.HOME ?? "";
 	if (home && filePath.startsWith(home)) {
 		const suffix = filePath.slice(home.length);
 		if (suffix === "" || suffix.startsWith("/")) return `~${suffix}`;
@@ -68,16 +69,6 @@ export function sanitizeStatusText(text: string): string {
 	return sanitizeLabel(text).trim();
 }
 
-/**
- * Same safety as {@link sanitizeStatusText} but without trimming, so a label
- * written as "TOK " keeps the space that separates it from its value.
- */
-export function sanitizeLabel(text: string): string {
-	return stripVTControlCharacters(text)
-		.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069\ufeff]/g, " ")
-		.replace(/ +/g, " ");
-}
-
 export function withIcon(icon: string, text: string): string {
 	return icon ? `${icon} ${text}` : text;
 }
@@ -149,5 +140,5 @@ export function getSessionAccentHex(name: string, themeColorHexes: string[]): st
 	let targetHue = DARK_HUE_START + (nameToHue(name) % range);
 	const themeHues = themeColorHexes.map(hexToHue).filter((h): h is number => h !== undefined);
 	targetHue = findSafeHue(targetHue, themeHues, DARK_HUE_START, DARK_HUE_END);
-	return rgbToHex(hslToRgb(targetHue, ACCENT_SATURATION, ACCENT_DARK_LIGHTNESS));
+	return colorToHex(rgbColor(...hslToRgb(targetHue, ACCENT_SATURATION, ACCENT_DARK_LIGHTNESS)));
 }

package/src/working-status-embed.ts

@@ -1,12 +1,5 @@
 import type { CustomEditor } from "@earendil-works/pi-coding-agent";
 
-/**
- * Event-bus channel on which this extension announces, as `{ embedded: boolean }`,
- * whether its bar hosts Pi's working status. pi-topping slides its loader's response
- * model out only while it does. Shared with pi-topping.
- */
-export const WORKING_STATUS_EMBED_CHANNEL = "pi-topping-statusline:working-status-embedded";
-
 type EmbeddingEditor = Partial<Pick<CustomEditor, "embedWorkingStatus" | "setWorkingStatusIndicator">>;
 
 /** Whether an editor this extension built draws the host's working status in its bar. */

package/src/working-status.ts

@@ -1,10 +1,9 @@
 import type { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { WORKING_STATUS_SLIDE_MS } from "@underactive/pi-topping-primitives/contracts";
 import { easeFade } from "./theme.js";
 
 export type StatusIndicatorKind = NonNullable<Parameters<CustomEditor["setWorkingStatusIndicator"]>[0]>["kind"];
 
-/** Slide-out time for a status that appears while the top-left group shows none. */
-export const STATUS_SLIDE_MS = 300;
 /** Briefly retain a cleared status so handoffs between host indicators do not flash. */
 export const STATUS_HOLD_MS = 150;
 /** Cross-fade budget when the embedded working status disappears: half out, half in. */
@@ -36,7 +35,7 @@ interface StatusExit {
  * Resolve host status-indicator handoffs into stable top-bar frames.
  *
  * A status that appears while the top-left group shows none slides out over
- * STATUS_SLIDE_MS. pi 0.86 routes working, retry, compaction, and
+ * WORKING_STATUS_SLIDE_MS. pi 0.86 routes working, retry, compaction, and
  * branch-summary indicators through the editor border and may clear the slot
  * between them. A cleared status is held briefly to bridge that gap, and a
  * status arriving while the previous one is still drawn takes its place
@@ -88,7 +87,7 @@ export class StatusTransition {
 	pending(now: number): boolean {
 		const exit = this.#exit;
 		if (exit) return now < exit.holdUntil + exit.fadeMs;
-		return this.#slideFrom !== undefined && now < this.#slideFrom + STATUS_SLIDE_MS;
+		return this.#slideFrom !== undefined && now < this.#slideFrom + WORKING_STATUS_SLIDE_MS;
 	}
 
 	reset(): void {
@@ -108,7 +107,7 @@ export class StatusTransition {
 	 */
 	#withSlide(frame: StatusFrame, now: number): StatusFrame {
 		if (this.#slideFrom === undefined) return frame;
-		const progress = (now - this.#slideFrom) / STATUS_SLIDE_MS;
+		const progress = (now - this.#slideFrom) / WORKING_STATUS_SLIDE_MS;
 		if (progress >= 1) {
 			this.#slideFrom = undefined;
 			return frame;