@underactive/pi-topping-statusline 0.1.0

package/src/token-rate.ts

@@ -0,0 +1,242 @@
+/**
+ * Live tok/s monitor for the token_rate segment.
+ *
+ * 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):
+ *
+ * - text/thinking deltas are counted as approximate tokens (word boundaries);
+ * - an EMA (alpha 0.4) smooths 100ms samples into a rate;
+ * - message_end reconciles the estimate against exact usage.output;
+ * - the last rate holds for HOLD_MS, fades over FADE_MS, then goes idle.
+ *
+ * The segment itself never disappears: idle renders as `--- tok/s`.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { FADE_SHADE_COUNT } from "./theme.js";
+import type { TokenRateDisplay } from "./types.js";
+
+const SAMPLE_INTERVAL_MS = 100;
+/** pi-topping TOKEN_RATE_HOLD_MS — retained value stays at full color. */
+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 = "default"): 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;
+	#enabled = false;
+	#busy = false;
+	#timer: ReturnType<typeof setInterval> | undefined;
+
+	// Token accounting: exact usage from message_end + live estimate since.
+	#confirmTokens = 0;
+	#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;
+	#lastRendered: TokenRateDisplay | undefined;
+
+	constructor(requestRender: () => void) {
+		this.#requestRender = requestRender;
+	}
+
+	attach(pi: ExtensionAPI): void {
+		pi.on("agent_start", () => {
+			if (!this.#enabled) return;
+			this.#busy = true;
+			this.#resetTurn();
+			this.#startTimer();
+		});
+		pi.on("agent_settled", () => {
+			if (!this.#enabled) return;
+			this.#busy = false;
+		});
+		pi.on("message_start", event => {
+			if (!this.#enabled || event.message.role !== "assistant") return;
+			this.#liveTokens = 0;
+			this.#counter.reset();
+		});
+		pi.on("message_update", event => {
+			if (!this.#enabled) return;
+			const assistantEvent = event.assistantMessageEvent;
+			if (assistantEvent.type === "text_delta" || assistantEvent.type === "thinking_delta") {
+				this.#liveTokens += this.#counter.count(assistantEvent.delta, assistantEvent.type);
+			}
+		});
+		pi.on("message_end", event => {
+			if (!this.#enabled || event.message.role !== "assistant") return;
+			const exact = event.message.usage?.output;
+			this.#confirmTokens += exact ?? this.#liveTokens;
+			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.#liveTokens = 0;
+			this.#counter.reset();
+		});
+	}
+
+	/** Events are only processed in TUI sessions; index.ts gates on mode. */
+	enable(): void {
+		this.#enabled = true;
+	}
+
+	disable(): void {
+		this.#enabled = false;
+		this.#busy = false;
+		this.#stopTimer();
+		this.#resetTurn();
+	}
+
+	/** 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 };
+	}
+
+	#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;
+	}
+
+	#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) {
+			this.#stopTimer();
+		}
+		const display = this.getDisplay(now);
+		if (
+			!this.#lastRendered ||
+			display.rate !== this.#lastRendered.rate ||
+			display.phase !== this.#lastRendered.phase ||
+			display.fadeShade !== this.#lastRendered.fadeShade
+		) {
+			this.#lastRendered = display;
+			this.#requestRender();
+		}
+	}
+
+	#startTimer(): void {
+		this.#timer ??= setInterval(() => this.#tick(), SAMPLE_INTERVAL_MS);
+		this.#timer.unref?.();
+	}
+
+	#stopTimer(): void {
+		if (this.#timer) {
+			clearInterval(this.#timer);
+			this.#timer = undefined;
+		}
+	}
+}

package/src/types.ts

@@ -0,0 +1,166 @@
+/**
+ * Ported from oh-my-pi status-line/types.ts, trimmed to the fields a pi
+ * extension can populate. SegmentContext is a plain snapshot; segments are
+ * pure functions over it.
+ */
+import type { BorderStyle, SymbolPreset } from "./theme.js";
+
+export type StatusLineSeparatorStyle = "powerline" | "powerline-thin" | "slash" | "pipe" | "ascii";
+
+export type StatusLineSegmentId =
+	| "pi"
+	| "model"
+	| "path"
+	| "git"
+	| "pr"
+	| "session_name"
+	| "pi_stats"
+	| "token_rate"
+	| "feeds"
+	| "context_graph"
+	| "scroll_hint";
+
+/**
+ * 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
+ * object to display, and `prefix` is the literal label drawn before it.
+ */
+export interface StatusLineFeed {
+	customType: string;
+	field: string;
+	prefix: string;
+	format: FeedFormat;
+}
+
+/**
+ * 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.
+ */
+export type FeedFormat = "currency" | "number" | "text";
+
+export interface StatusLineSegmentToggles {
+	pi?: boolean;
+	model?: boolean;
+	provider?: boolean;
+	thinking?: boolean;
+	path?: boolean;
+	git?: boolean;
+	pr?: boolean;
+	sessionName?: boolean;
+	tokenRateTopRight?: boolean;
+	piStats?: boolean;
+	tokenRate?: boolean;
+	feeds?: boolean;
+	feedsBottomLeft?: boolean;
+	tokenRateBottomLeft?: boolean;
+	contextBar?: boolean;
+	contextStats?: boolean;
+	scrollHint?: boolean;
+}
+
+/** On-disk shape of ~/.pi/agent/pi-topping-statusline/settings.json. */
+export interface StatusLineSettings {
+	/** Drop the bar's bg fill and round caps so it inherits the terminal bg. */
+	transparent?: boolean;
+	separator?: StatusLineSeparatorStyle;
+	symbols?: SymbolPreset;
+	borderStyle?: BorderStyle;
+	segments?: StatusLineSegmentToggles;
+	feeds?: StatusLineFeed[];
+	/** Animated rainbow border while the thinking level is max. */
+	rainbowBorder?: boolean;
+}
+
+/** Resolved per-segment render options; resolveEffectiveSettings always fills them. */
+export interface StatusLineSegmentOptions {
+	model: { showModel: boolean; showProvider: boolean; showThinking: boolean };
+	path: { abbreviate: boolean; maxLength: number; stripWorkPrefix: boolean };
+	context: { showBar: boolean; showStats: boolean };
+	/** Subscriptions rendered by the feeds segment, in display order. */
+	feeds: StatusLineFeed[];
+}
+
+/** Which segment groups a build() snapshot needs to populate. */
+export interface SegmentIncludes {
+	git: boolean;
+	pr: boolean;
+	piStats: boolean;
+	tokenRate: boolean;
+	feeds: readonly string[];
+}
+
+export interface EffectiveStatusLineSettings {
+	transparent: boolean;
+	separator: StatusLineSeparatorStyle;
+	symbols: SymbolPreset;
+	borderStyle: BorderStyle;
+	leftSegments: StatusLineSegmentId[];
+	rightSegments: StatusLineSegmentId[];
+	bottomLeftSegments: StatusLineSegmentId[];
+	bottomRightSegments: StatusLineSegmentId[];
+	segmentOptions: StatusLineSegmentOptions;
+	rainbowBorder: boolean;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Segment rendering
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SegmentContext {
+	options: StatusLineSegmentOptions;
+	model: { name?: string; id: string; provider: string; reasoning: boolean } | undefined;
+	thinkingLevel: string;
+	cwd: string;
+	sessionName: string | undefined;
+	/** Context usage percent, or null when unknown (e.g. right after compaction). */
+	contextPercent: number | null;
+	contextTokens: number;
+	contextWindow: number;
+	git: {
+		branch: string | null;
+		status: { staged: number; unstaged: number; untracked: number } | null;
+		pr: { number: number; url: string } | null;
+	};
+	/** Set when cwd is a linked git worktree; path segment collapses to project name. */
+	worktree: { projectName: string; worktreeName: string } | null;
+	/** Scroll hint extracted from the editor's lower border, if present. */
+	scrollHint: string | undefined;
+	/** Pi's own footer stats, when this frame needs them. */
+	piStats: string | undefined;
+	/** Live tok/s display state, when this frame needs it. */
+	tokenRate: TokenRateDisplay | undefined;
+	/**
+	 * Newest in-run data payload per subscribed customType. A customType is
+	 * absent when no extension publishes it, or when it has published nothing
+	 * since this run began — a resumed session still carries the previous run's
+	 * entries, and those must not be shown as current.
+	 */
+	feedData: Record<string, unknown> | undefined;
+}
+
+export type TokenRatePhase = "active" | "fading" | "idle";
+
+export interface TokenRateDisplay {
+	/** Smoothed rate at last token arrival; null when idle (segment shows `---`). */
+	rate: number | null;
+	phase: TokenRatePhase;
+	/** Discrete fade step (0..FADE_SHADE_COUNT-1); only meaningful when fading. */
+	fadeShade: number;
+}
+
+export interface RenderedSegment {
+	content: string;
+	visible: boolean;
+}
+
+export interface StatusLineSegment {
+	id: StatusLineSegmentId;
+	render(ctx: SegmentContext): RenderedSegment;
+}
+
+export interface SeparatorDef {
+	left: string;
+	right: string;
+}

package/src/utils.ts

@@ -0,0 +1,161 @@
+/**
+ * Formatting helpers and the session-accent color algorithm, ported from
+ * oh-my-pi (packages/utils/src/format.ts, packages/coding-agent/src/utils/
+ * 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 { parseHex } from "./theme.js";
+
+export function formatNumber(n: number): string {
+	if (n < 1_000) return n.toString();
+	if (n < 10_000) return `${(n / 1_000).toFixed(1)}K`;
+	if (n < 1_000_000) return `${Math.round(n / 1_000)}K`;
+	if (n < 10_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	if (n < 1_000_000_000) return `${Math.round(n / 1_000_000)}M`;
+	if (n < 10_000_000_000) return `${(n / 1_000_000_000).toFixed(1)}B`;
+	return `${Math.round(n / 1_000_000_000)}B`;
+}
+
+export function shortenPath(filePath: string, homeDir?: string): string {
+	const home = homeDir ?? process.env.HOME ?? "";
+	if (home && filePath.startsWith(home)) {
+		const suffix = filePath.slice(home.length);
+		if (suffix === "" || suffix.startsWith("/")) return `~${suffix}`;
+	}
+	return filePath;
+}
+
+/**
+ * Clamp a path/label to `maxLen` by eliding middle components with `…`.
+ * The first folder (after `~` or the root) and the basename survive longest;
+ * middle components drop farthest-from-cwd first. Falls back to plain
+ * left-truncation once even `…/basename` overflows.
+ */
+export function clampPathLength(pwd: string, maxLen: number): string {
+	if (pwd.length <= maxLen) return pwd;
+
+	const parts = pwd.split("/");
+	const last = parts.length - 1;
+	const firstIdx = parts[0] === "" || parts[0] === "~" ? 1 : 0;
+
+	for (let dropped = 1; dropped <= last - firstIdx - 1; dropped++) {
+		const candidate = [...parts.slice(0, firstIdx + 1), "…", ...parts.slice(firstIdx + 1 + dropped)].join("/");
+		if (candidate.length <= maxLen) return candidate;
+	}
+
+	// The first folder no longer fits: keep whatever remains closest to the cwd.
+	for (let start = firstIdx + 1; start <= last; start++) {
+		const candidate = `…/${parts.slice(start).join("/")}`;
+		if (candidate.length <= maxLen) return candidate;
+	}
+
+	return `…${pwd.slice(-Math.max(0, maxLen - 1))}`;
+}
+
+/** Strip ANSI/VT escapes, map control chars to spaces, collapse whitespace. */
+export function sanitizeStatusText(text: string): string {
+	return stripVTControlCharacters(text)
+		.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+		.replace(/ +/g, " ")
+		.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]/g, " ")
+		.replace(/ +/g, " ");
+}
+
+export function withIcon(icon: string, text: string): string {
+	return icon ? `${icon} ${text}` : text;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Session accent (djb2 hue hash, dark warm band, collision avoidance)
+// ═══════════════════════════════════════════════════════════════════════════
+
+function nameToHue(name: string): number {
+	let hash = 5381;
+	for (let i = 0; i < name.length; i++) {
+		hash = ((hash << 5) + hash) ^ name.charCodeAt(i);
+		hash = hash >>> 0;
+	}
+	return hash % 360;
+}
+
+const ACCENT_SATURATION = 0.9;
+const ACCENT_DARK_LIGHTNESS = 0.72;
+const MIN_HUE_DISTANCE = 10;
+const MIN_SATURATION_FOR_HUE = 0.1;
+const DARK_HUE_START = 0;
+const DARK_HUE_END = 120;
+
+function hueDistance(a: number, b: number): number {
+	const d = Math.abs(a - b);
+	return Math.min(d, 360 - d);
+}
+
+function hexToHue(hex: string): number | undefined {
+	const rgb = parseHex(hex);
+	if (!rgb) return undefined;
+	const r = rgb[0] / 255;
+	const g = rgb[1] / 255;
+	const b = rgb[2] / 255;
+	const max = Math.max(r, g, b);
+	const min = Math.min(r, g, b);
+	const delta = max - min;
+	const s = max === 0 ? 0 : delta / max;
+	if (s < MIN_SATURATION_FOR_HUE) return undefined;
+	let h: number;
+	if (delta === 0) h = 0;
+	else if (max === r) h = 60 * (((g - b) / delta) % 6);
+	else if (max === g) h = 60 * ((b - r) / delta + 2);
+	else h = 60 * ((r - g) / delta + 4);
+	return (h + 360) % 360;
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+	const c = (1 - Math.abs(2 * l - 1)) * s;
+	const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+	const m = l - c / 2;
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	if (h < 60) [r, g, b] = [c, x, 0];
+	else if (h < 120) [r, g, b] = [x, c, 0];
+	else if (h < 180) [r, g, b] = [0, c, x];
+	else if (h < 240) [r, g, b] = [0, x, c];
+	else if (h < 300) [r, g, b] = [x, 0, c];
+	else [r, g, b] = [c, 0, x];
+	const toHex = (v: number) =>
+		Math.round((v + m) * 255)
+			.toString(16)
+			.padStart(2, "0");
+	return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
+function findSafeHue(target: number, occupied: number[], lo: number, hi: number): number {
+	if (occupied.length === 0) return target;
+	if (occupied.every(h => hueDistance(target, h) >= MIN_HUE_DISTANCE)) return target;
+	for (let d = 1; d <= hi - lo; d++) {
+		for (const dir of [1, -1]) {
+			const candidate = Math.max(lo, Math.min(hi, target + d * dir));
+			if (occupied.every(h => hueDistance(candidate, h) >= MIN_HUE_DISTANCE)) return candidate;
+		}
+	}
+	return target;
+}
+
+/** Stable accent hex for a session name (OMP's dark-theme path). */
+export function getSessionAccentHex(name: string, themeColorHexes: string[]): string {
+	const range = DARK_HUE_END - DARK_HUE_START;
+	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 hslToHex(targetHue, ACCENT_SATURATION, ACCENT_DARK_LIGHTNESS);
+}