@henryqw/pi-footer 4.1.2 → 4.2.0

package/README.md

@@ -96,12 +96,54 @@ Statuses from other extensions, including Ponytail and `pi-rewind`, share the le
 
 ## Config
 
-Package-owned: `~/.pi/agent/config/pi-open-in/config.json` (under `getAgentDir()` when overridden). The retained `pi-open-in` home belongs to the open commands now shipped here.
+Package-owned: `~/.pi/agent/config/pi-footer/config.json` for footer colors and `~/.pi/agent/config/pi-open-in/config.json` for the open command (both under `getAgentDir()` when overridden). The retained `pi-open-in` home belongs to the open commands now shipped here.
 
 | Name | Description | Values | Default |
 | --- | --- | --- | --- |
+| `colors` | Colors for footer-owned text by role. | Object that maps color roles to theme tokens, `#RGB`, `#RRGGBB`, `oklch(...)`, `okhsl(...)`, or an ANSI index from `0` to `255`. | Built-in colors. |
 | `command` | Command that `/open` runs. Required when the file exists. | Non-empty string. | `"code"` |
 
+The footer reads `colors` once per session start; run `/reload` after editing it. The file is never rewritten. A missing file or a missing role keeps the built-in color. At each session start, an invalid file shows a notification with the path and the reason, and the whole color config falls back to the built-in colors.
+
+### Footer color roles
+
+Every role is optional:
+
+| Role | Surface |
+| --- | --- |
+| `repository` | Repository name on the first line. |
+| `branch` | Branch or checkout name, still hyperlink-wrapped when the terminal supports it. |
+| `gitStatus` | Git badges such as `[+2 ~3 ↑1]`. |
+| `input`, `output`, `cache`, `throughput`, `cost`, `context` | The six usage metrics on the second line. |
+| `model` | Active model and routed physical model. |
+| `runtime` | Cumulative agent-work time on the third line. |
+| `codegraphActive` | The `● CG` badge during a direct `codegraph_explore` call. |
+| `separator` | Middle dots, bullets, arrows, and the truncation ellipsis. |
+
+```json
+{
+  "colors": {
+    "repository": "muted",
+    "branch": "accent",
+    "gitStatus": "warning",
+    "input": "#4ec9b0",
+    "output": "#9cdcfe",
+    "cache": "#c586c0",
+    "throughput": "#dcdcaa",
+    "cost": "#ce9178",
+    "context": "#89d185",
+    "model": "text",
+    "runtime": "muted",
+    "codegraphActive": "accent",
+    "separator": "dim"
+  }
+}
+```
+
+Theme tokens are `accent`, `dim`, `muted`, `text`, `success`, `warning`, `error`, and `thinkingText`. Thinking levels keep their built-in gradient, and statuses from other extensions keep their producer colors; the `colors` object controls neither.
+
+### Open command
+
 A missing file silently uses the default command, `code`. An invalid existing file makes `/open` fail visibly and stays unchanged. See Limits and recovery. `/open` reads the config on every run. Only `/set-open-in` writes the file, atomically. Reads do not create or write the config home.
 
 ## API

package/extensions/footer-config.ts

@@ -0,0 +1,103 @@
+import { extensionConfigPath, createConfigStore } from "@henryqw/pi-config-store";
+import { parseColor, type Color } from "@earendil-works/pi-tui";
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Color roles for footer-owned content; external extension statuses and the thinking gradient are not covered. */
+export const FOOTER_COLOR_ROLES = [
+	"repository",
+	"branch",
+	"gitStatus",
+	"input",
+	"output",
+	"cache",
+	"throughput",
+	"cost",
+	"context",
+	"model",
+	"runtime",
+	"codegraphActive",
+	"separator",
+] as const;
+
+export type FooterColorRole = (typeof FOOTER_COLOR_ROLES)[number];
+
+/** Theme foreground tokens accepted as config values. */
+const THEME_TOKENS: ReadonlySet<ThemeColor> = new Set<ThemeColor>([
+	"accent",
+	"dim",
+	"muted",
+	"text",
+	"success",
+	"warning",
+	"error",
+	"thinkingText",
+]);
+
+export type FooterColorValue = { kind: "token"; token: ThemeColor } | { kind: "color"; color: Color };
+
+export type FooterColorConfig = Partial<Record<FooterColorRole, FooterColorValue>>;
+
+function parseColorValue(role: string, raw: unknown): FooterColorValue {
+	if (typeof raw === "number") {
+		if (!Number.isInteger(raw) || raw < 0 || raw > 255) {
+			throw new Error(`colors.${role}: ANSI index must be an integer from 0 to 255`);
+		}
+		return { kind: "color", color: parseColor(raw) };
+	}
+	if (typeof raw !== "string" || !raw.trim()) {
+		throw new Error(`colors.${role}: expected a theme token or a color value`);
+	}
+	if (THEME_TOKENS.has(raw as ThemeColor)) return { kind: "token", token: raw as ThemeColor };
+	try {
+		return { kind: "color", color: parseColor(raw) };
+	} catch {
+		throw new Error(`colors.${role}: invalid color "${raw}"`);
+	}
+}
+
+/** Validates and converts the config file; throws on a present-but-invalid file so the caller decides the fallback. */
+export function parseFooterColorConfig(value: unknown): { colors: FooterColorConfig } {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("config must be a JSON object");
+	}
+	const root = value as Record<string, unknown>;
+	const unknown = Object.keys(root).filter((key) => key !== "colors");
+	if (unknown.length > 0) throw new Error(`unknown field(s): ${unknown.join(", ")}`);
+	if (!("colors" in root)) throw new Error('missing "colors" field');
+	if (!root.colors || typeof root.colors !== "object" || Array.isArray(root.colors)) {
+		throw new Error('"colors" must be an object');
+	}
+	const colors: FooterColorConfig = {};
+	for (const [role, raw] of Object.entries(root.colors as Record<string, unknown>)) {
+		if (!FOOTER_COLOR_ROLES.includes(role as FooterColorRole)) {
+			throw new Error(`unknown color role "${role}"`);
+		}
+		colors[role as FooterColorRole] = parseColorValue(role, raw);
+	}
+	return { colors };
+}
+
+function createFooterConfigStore(agentDir?: string) {
+	return createConfigStore<{ colors: FooterColorConfig }>({
+		extensionId: "pi-footer",
+		agentDir,
+		defaults: () => ({ colors: {} }),
+		parse: parseFooterColorConfig,
+	});
+}
+
+/** Reads the color config; a missing file yields empty colors (built-in colors), an invalid file throws. */
+export function loadFooterConfig(agentDir?: string): FooterColorConfig {
+	return createFooterConfigStore(agentDir).loadSync().value.colors;
+}
+
+/** Config file path, used in error notifications. */
+export function footerConfigPath(agentDir?: string): string {
+	return extensionConfigPath("pi-footer", agentDir);
+}
+
+/** An explicit config wins; otherwise fall back to the caller's semantic token. */
+export function paintFooter(theme: Theme, value: FooterColorValue | undefined, fallback: ThemeColor, text: string): string {
+	if (value === undefined) return theme.fg(fallback, text);
+	return value.kind === "token" ? theme.fg(value.token, text) : theme.style(text, { fg: value.color });
+}

package/extensions/footer.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join } from "node:path";
 import type { ExtensionAPI, ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
 import { getCapabilities, hyperlink, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { configuredOpenUri } from "./open.ts";
+import { type FooterColorConfig, footerConfigPath, loadFooterConfig, paintFooter } from "./footer-config.ts";
 
 const THINKING_COLORS = {
 	minimal: 46,
@@ -15,6 +16,8 @@ const THINKING_COLORS = {
 const QUOTA_STATUS_KEY = "pi-multi-codex";
 const AGENT_TIME_ENTRY = "pi-footer:agent-work";
 const SUBAGENT_BACKGROUND_RESULT = "subagent-background-result";
+// Shorter windows are bursts (non-streamed fallbacks, one large chunk) or too coarse to time.
+const MIN_TPS_WINDOW_MS = 250;
 /** Pi's VIRTUAL_MODEL_API: catalog entries that route each request to a physical model. */
 const VIRTUAL_MODEL_API = "pi-virtual";
 
@@ -284,9 +287,9 @@ export default function footerExtension(pi: ExtensionAPI): void {
 		pi.on("message_end", (event) => {
 			if (event.message.role !== "assistant") return;
 			const output = event.message.usage?.output ?? 0;
-			const seconds = assistantStartedAt === undefined ? 0 : (assistantLastUpdateAt! - assistantStartedAt) / 1000;
+			const milliseconds = assistantStartedAt === undefined ? 0 : assistantLastUpdateAt! - assistantStartedAt;
 			assistantStartedAt = assistantLastUpdateAt = undefined;
-			tps = seconds > 0 ? output / seconds : undefined;
+			tps = milliseconds >= MIN_TPS_WINDOW_MS ? output / (milliseconds / 1000) : undefined;
 		});
 
 		// Session entries are append-only; the leaf also changes on tree navigation.
@@ -324,6 +327,14 @@ export default function footerExtension(pi: ExtensionAPI): void {
 			}
 		};
 
+		// Colors are read once per session start; /reload applies edits
+		let footerColors: FooterColorConfig = {};
+		try {
+			footerColors = loadFooterConfig();
+		} catch (error) {
+			ctx.ui.notify(`Footer colors ignored (${footerConfigPath()}): ${(error as Error).message}`, "error");
+		}
+
 		ctx.ui.setFooter((tui, theme, data) => {
 			requestRuntimeRender = () => tui.requestRender();
 			const unsubscribe = data.onBranchChange(() => {
@@ -353,7 +364,7 @@ export default function footerExtension(pi: ExtensionAPI): void {
 					const extensionStatuses = data.getExtensionStatuses();
 					const prStatus = sanitizeStatus(extensionStatuses.get("pi-pr") ?? "");
 					const codegraph = activeCodegraphCalls.size > 0
-						? `${theme.fg("accent", "●")} CG`
+						? `${paintFooter(theme, footerColors.codegraphActive, "accent", "●")} CG`
 						: sanitizeStatus(extensionStatuses.get("pi-codegraph") ?? "");
 					const quotaStatus = sanitizeStatus(extensionStatuses.get(QUOTA_STATUS_KEY) ?? "");
 					const externalStatuses: string[] = [];
@@ -362,38 +373,42 @@ export default function footerExtension(pi: ExtensionAPI): void {
 						const text = sanitizeStatus(value);
 						if (text) externalStatuses.push(text);
 					}
-					const ellipsis = theme.fg("dim", "…");
-					const usage = theme.fg("dim", [
-						`↑ ${formatTokens(input)}`,
-						`↓ ${formatTokens(output)}`,
-						`↺ ${cacheRate === undefined ? "—" : `${cacheRate.toFixed(1)}%`}`,
-						`⚡ ${tps === undefined ? "—" : `${tps.toFixed(1)} t/s`}`,
-					`$ ${cost.toFixed(3)}`,
-						`◔ ${context == null ? "—" : `${context.toFixed(1)}%`}`,
-					].join(" · "));
+					const sep = (text: string) => paintFooter(theme, footerColors.separator, "dim", text);
+					// Previously uncolored joins only take the separator color when it is configured, keeping the default look
+					const plainSep = (text: string) =>
+						footerColors.separator === undefined ? text : paintFooter(theme, footerColors.separator, "dim", text);
+					const ellipsis = sep("…");
+					const usage = [
+						paintFooter(theme, footerColors.input, "dim", `↑ ${formatTokens(input)}`),
+						paintFooter(theme, footerColors.output, "dim", `↓ ${formatTokens(output)}`),
+						paintFooter(theme, footerColors.cache, "dim", `↺ ${cacheRate === undefined ? "—" : `${cacheRate.toFixed(1)}%`}`),
+						paintFooter(theme, footerColors.throughput, "dim", `⚡ ${tps === undefined ? "—" : `${tps.toFixed(1)} t/s`}`),
+						paintFooter(theme, footerColors.cost, "dim", `$ ${cost.toFixed(3)}`),
+						paintFooter(theme, footerColors.context, "dim", `◔ ${context == null ? "—" : `${context.toFixed(1)}%`}`),
+					].join(sep(" · "));
 					const thinkingText = (level: string) => {
 						const thinkingColor = THINKING_COLORS[level as keyof typeof THINKING_COLORS];
 						return level === "ultra" ? rainbow(level) : thinkingColor === undefined ? theme.fg("dim", level) : color(level, thinkingColor);
 					};
-					const selected = theme.fg("dim", `${ctx.model?.id ?? "no-model"} • `) + thinkingText(String(ctx.thinkingLevel ?? "off"));
+					const selected = paintFooter(theme, footerColors.model, "dim", `${ctx.model?.id ?? "no-model"}`) + sep(" • ") + thinkingText(String(ctx.thinkingLevel ?? "off"));
 					// Under a virtual selection, show where the latest request went, as Pi's own footer does.
 					const model = ctx.model?.api === VIRTUAL_MODEL_API && routed
-						? selected + theme.fg("dim", ` → ${routed.model}`) + (routed.thinkingLevel ? theme.fg("dim", " • ") + thinkingText(routed.thinkingLevel) : "")
+						? selected + sep(" → ") + paintFooter(theme, footerColors.model, "dim", routed.model) + (routed.thinkingLevel ? sep(" • ") + thinkingText(routed.thinkingLevel) : "")
 						: selected;
 					const elapsed = activeMilliseconds + (activeStartedAt === undefined ? 0 : performance.now() - activeStartedAt);
-					const runtime = theme.fg("dim", `◷ ${formatDuration(elapsed)}`);
-					const identity = branch ? theme.fg("dim", `${repo} · `) : "";
+					const runtime = paintFooter(theme, footerColors.runtime, "dim", `◷ ${formatDuration(elapsed)}`);
+					const identity = branch ? paintFooter(theme, footerColors.repository, "dim", repo) + sep(" · ") : "";
 					const checkout = branch ?? repo;
-					const checkoutLink = openUri && getCapabilities().hyperlinks
-						? hyperlink(theme.fg("accent", checkout), openUri)
-						: theme.fg("dim", checkout);
-					const checkoutStatus = gitSummary.badges ? `${checkoutLink} ${theme.fg("dim", gitSummary.badges)}` : checkoutLink;
-					const identityLine = prStatus ? `${identity}${checkoutStatus} · ${prStatus}` : `${identity}${checkoutStatus}`;
+					const linkUri = getCapabilities().hyperlinks ? openUri : undefined;
+					const checkoutText = paintFooter(theme, footerColors.branch, linkUri ? "accent" : "dim", checkout);
+					const checkoutLink = linkUri ? hyperlink(checkoutText, linkUri) : checkoutText;
+					const checkoutStatus = gitSummary.badges ? `${checkoutLink} ${paintFooter(theme, footerColors.gitStatus, "dim", gitSummary.badges)}` : checkoutLink;
+					const identityLine = prStatus ? `${identity}${checkoutStatus}${plainSep(" · ")}${prStatus}` : `${identity}${checkoutStatus}`;
 					const firstLine = quotaStatus ? align(identityLine, quotaStatus, width, ellipsis) : identityLine;
 					const lines = [
 						firstLine,
 						align(usage, model, width, ellipsis),
-						alignRightReserved([codegraph, ...externalStatuses].filter(Boolean).join(" · "), runtime, width, ellipsis),
+						alignRightReserved([codegraph, ...externalStatuses].filter(Boolean).join(plainSep(" · ")), runtime, width, ellipsis),
 					];
 					return lines.map((line) => truncateToWidth(line, width, ellipsis));
 				},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-footer",
-  "version": "4.1.2",
+  "version": "4.2.0",
   "description": "Show repository and usage details in the Pi footer and open the current working directory.",
   "keywords": [
     "pi-package",