pi-chassis 0.0.0-stage → 0.7.1

package/extensions/chassis/palette.ts

@@ -0,0 +1,258 @@
+/**
+ * Colours and width-safe text helpers.
+ *
+ * The chrome follows the active theme. The few colours that come from the brand (see brand.ts)
+ * are the primary mark colour, the plan-mode colour, a quiet neutral, and the two surface shades.
+ */
+
+import { homedir } from "node:os";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { backgroundAnsi, type Color, colorToHex, colorToOkhsl, colorToRgb, foregroundAnsi, okhslColor, parseColor, rgbColor, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { WidgetColor, WidgetLevel } from "./api.ts";
+import { type BrandColors, type BrandSurfaces, getBrand } from "./brand.ts";
+import { safeGlyph } from "./icons.ts";
+import { scrubText } from "./sanitize.ts";
+
+const parsed = new Map<string, Color>();
+
+/** Parse a colour string once; an unusable value falls back to `fallback`. */
+export function toColor(value: string, fallback = "#808080"): Color {
+	let c = parsed.get(value);
+	if (!c) {
+		try {
+			c = parseColor(value);
+		} catch {
+			c = toColor(fallback, "#808080");
+		}
+		parsed.set(value, c);
+	}
+	return c;
+}
+
+/** A brand colour, parsed. */
+export const brandColor = (name: keyof BrandColors): Color => toColor(getBrand().colors[name]);
+
+/** Paint text with a concrete colour, honouring the theme's colour mode (truecolor/256). */
+export function paint(theme: Theme, color: Color, text: string): string {
+	return `${foregroundAnsi(color, theme.getColorMode())}${text}\x1b[39m`;
+}
+
+/** True under a light theme. A theme without an `appearance` (a test double) counts as dark. */
+export const isLight = (theme: Theme): boolean => theme.appearance === "light";
+
+/** Relative luminance of a colour, 0 (black) to 1 (white). */
+function luminance(color: Color): number {
+	const { r, g, b } = colorToRgb(color);
+	const lin = (v: number) => (v / 255 <= 0.03928 ? v / 255 / 12.92 : ((v / 255 + 0.055) / 1.055) ** 2.4);
+	return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio of two colours, 1 to 21. */
+export function contrast(a: Color, b: Color): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x) as [number, number];
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+const readableCache = new Map<string, Color>();
+
+/**
+ * `color` moved along its own lightness (hue and saturation kept) until it has at least `min`
+ * contrast against `bg`: darker on a light background, lighter on a dark one. A colour that is
+ * readable already comes back as it is. On a background in the middle, where that direction cannot
+ * reach `min`, the other direction is tried; failing both, black or white, whichever reads better.
+ */
+export function readableOn(color: Color, bg: Color, min = 4.5): Color {
+	if (contrast(color, bg) >= min) return color;
+	const key = `${colorToHex(color)}|${colorToHex(bg)}|${min}`;
+	let out = readableCache.get(key);
+	if (!out) {
+		const { h, s, l } = colorToOkhsl(color);
+		const towardsDark = luminance(bg) > 0.5;
+		const search = (step: number): Color | undefined => {
+			for (let i = 1; i <= 50; i++) {
+				const c = okhslColor(h, s, Math.min(1, Math.max(0, l + step * i)));
+				if (contrast(c, bg) >= min) return c;
+			}
+			return undefined;
+		};
+		const black = rgbColor(0, 0, 0);
+		const white = rgbColor(255, 255, 255);
+		out = search(towardsDark ? -0.02 : 0.02) ?? search(towardsDark ? 0.02 : -0.02) ?? (contrast(black, bg) >= contrast(white, bg) ? black : white);
+		readableCache.set(key, out);
+	}
+	return out;
+}
+
+/**
+ * A brand or widget colour used as text. On a light theme it is darkened until it can be read on the
+ * surfaces; on a dark theme it is used as given, which is how the brand colours were chosen.
+ */
+export const textColor = (theme: Theme, color: Color): Color => (isLight(theme) ? readableOn(color, surfaceColor(theme, "element")) : color);
+
+/** Text in the brand's primary colour: the active-mode mark, the brand glyph, the header art. */
+export const primary = (theme: Theme, text: string) => paint(theme, textColor(theme, brandColor("primary")), text);
+
+/**
+ * One frame of the working spinner: the glyph in the brand's primary colour, so it follows whatever
+ * brand is installed. A primary colour that cannot be parsed falls back to the theme's accent.
+ */
+export function spinnerFrame(theme: Theme, glyph: string): string {
+	try {
+		parseColor(getBrand().colors.primary);
+	} catch {
+		return theme.fg("accent", glyph);
+	}
+	return primary(theme, glyph);
+}
+
+/** Text in the brand's neutral colour. */
+export const neutral = (theme: Theme, text: string) => paint(theme, textColor(theme, brandColor("neutral")), text);
+
+/** Text in the plan-mode colour. */
+export const planColor = (theme: Theme, text: string) => paint(theme, textColor(theme, brandColor("plan")), text);
+
+/** The brand mark and name: "<glyph> <name>", or just the glyph. Painted; no version. */
+export function brandMark(theme: Theme): string {
+	const b = getBrand();
+	const glyph = primary(theme, safeGlyph(b.glyph));
+	return b.name ? `${glyph} ${theme.bold(theme.fg("text", b.name))}` : glyph;
+}
+
+/** "<mark> pi 1.1.0" (plus " · chassis 0.1.0" when given): the brand line on the home screen bottom bar and in the sidebar. */
+export function brandLine(theme: Theme, version: string, chassisVersion?: string): string {
+	const chassis = chassisVersion ? ` ${theme.fg("dim", "·")} ${theme.fg("muted", `chassis ${chassisVersion}`)}` : "";
+	return `${brandMark(theme)} ${theme.fg("muted", `pi ${version}`)}${chassis}`;
+}
+
+const LEVEL_COLOR: Record<WidgetLevel, WidgetColor> = {
+	ok: "success",
+	warn: "warning",
+	error: "error",
+	off: "dim",
+	info: "text",
+};
+
+/**
+ * Surface shades, OpenCode-style steps above the background (OpenCode: #0a0a0a, panel #141414,
+ * element #1e1e1e):
+ *   panel    sidebar, user messages, tool blocks
+ *   element  the prompt box
+ * The brand supplies the values: `surfaces` for a dark theme, `lightSurfaces` for a light one. A theme should use the same ones for userMessageBg,
+ * toolSuccessBg and customMessageBg, so pi's own blocks match ours.
+ */
+export type Surface = keyof BrandSurfaces;
+
+export const surfaceColor = (theme: Theme, surface: Surface): Color => {
+	const b = getBrand();
+	return toColor((isLight(theme) ? b.lightSurfaces : b.surfaces)[surface]);
+};
+
+export const surfaceBg = (theme: Theme, surface: Surface) => backgroundAnsi(surfaceColor(theme, surface), theme.getColorMode());
+
+/**
+ * Paint a line on a surface background across exactly `width` columns. Resets inside the line
+ * (\x1b[0m, \x1b[49m) would end the shading early, so the background is re-applied after each.
+ */
+export function shade(theme: Theme, line: string, width: number, surface: Surface = "panel"): string {
+	const bg = surfaceBg(theme, surface);
+	const body = fit(line, width).replace(/\x1b\[0m/g, `\x1b[0m${bg}`).replace(/\x1b\[49m/g, bg);
+	return `${bg}${body}\x1b[49m`;
+}
+
+/** Resolve a widget colour (theme token, brand colour or hex) and paint text with it. */
+export function widgetPaint(theme: Theme, color: WidgetColor | undefined, level: WidgetLevel | undefined, text: string): string {
+	const c = color ?? (level ? LEVEL_COLOR[level] : "text");
+	switch (c) {
+		case "brand":
+			return primary(theme, text);
+		case "brandDark":
+			return paint(theme, textColor(theme, brandColor("primaryDark")), text);
+		case "plan":
+			return planColor(theme, text);
+		default:
+			if (c.startsWith("#")) return paint(theme, textColor(theme, toColor(c)), text);
+			return theme.fg(c as Parameters<Theme["fg"]>[0], text);
+	}
+}
+
+/** Pad or truncate a (possibly styled) line to exactly `width` columns. */
+export function fit(line: string, width: number): string {
+	if (width <= 0) return "";
+	const t = truncateToWidth(line, width, "…");
+	return t + " ".repeat(Math.max(0, width - visibleWidth(t)));
+}
+
+export { sanitize, sanitizeKeepColor, sanitizeLines, scrubText, stripEscapes } from "./sanitize.ts";
+
+/** True if a string sets its own foreground colour. */
+export function hasOwnColor(text: string): boolean {
+	for (const m of text.matchAll(/\x1b\[([0-9;:]*)m/g)) {
+		const params = m[1]!.split(/[;:]/).map(Number);
+		for (let i = 0; i < params.length; i++) {
+			const p = params[i]!;
+			if ((p >= 30 && p <= 37) || (p >= 90 && p <= 97) || p === 38) return true;
+			if (p === 48) i += params[i + 1] === 2 ? 4 : 2;
+		}
+	}
+	return false;
+}
+
+export function fmtTokens(n: number): string {
+	if (!Number.isFinite(n) || n < 1000) return String(Math.max(0, Math.round(n || 0)));
+	if (n < 10_000) return `${(n / 1000).toFixed(1)}k`;
+	if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+	if (n < 10_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(n / 1_000_000)}M`;
+}
+
+export function fmtDuration(ms: number): string {
+	const s = Math.max(0, Math.floor(ms / 1000));
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	if (m < 60) return `${m}m ${s % 60}s`;
+	return `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+
+/** "just now", "5m ago", "3h ago", "2d ago", "6w ago". */
+export function fmtAgo(ms: number): string {
+	const m = Math.floor(Math.max(0, ms) / 60_000);
+	if (m < 1) return "just now";
+	if (m < 60) return `${m}m ago`;
+	const h = Math.floor(m / 60);
+	if (h < 24) return `${h}h ago`;
+	const d = Math.floor(h / 24);
+	if (d < 14) return `${d}d ago`;
+	return `${Math.floor(d / 7)}w ago`;
+}
+
+/**
+ * `path` as shown on screen: the home directory written as `~`, and escape sequences and control
+ * characters removed, because a directory name is chosen by whoever made the directory. Uses the OS
+ * home directory (HOME on Unix, the user profile on Windows) and accepts either path separator
+ * after it.
+ */
+export function homeRelative(path: string): string {
+	return scrubText(withTilde(path));
+}
+
+function withTilde(path: string): string {
+	let home: string;
+	try {
+		home = homedir();
+	} catch {
+		return path;
+	}
+	if (!home) return path;
+	const sameCase = (a: string, b: string) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
+	if (sameCase(path, home)) return "~";
+	const head = path.slice(0, home.length);
+	const next = path[home.length];
+	return sameCase(head, home) && (next === "/" || next === "\\") ? `~${path.slice(home.length)}` : path;
+}
+
+/** Index of the last path separator ("/" or "\\"), or -1. */
+export function lastSep(path: string): number {
+	return Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+}
+
+export const finite = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);

package/extensions/chassis/peek.ts

@@ -0,0 +1,167 @@
+/**
+ * Thinking peek: while the model reasons with thinking blocks hidden, replace pi's
+ * "Thinking..." label with a spinner and the tail of the reasoning.
+ *
+ * Adapted from pi-open-tui's peek.ts (MIT, Copyright (c) 2026 pi-open-tui contributors;
+ * see THIRD_PARTY_NOTICES).
+ *
+ * pi only offers a global setHiddenThinkingLabel(), which would rewrite every past message's
+ * label. To update just the streaming message, this finds the latest AssistantMessageComponent
+ * (duck-typed: setHiddenThinkingLabel + updateContent) in the TUI tree, as pi-open-tui does.
+ */
+
+import type { TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { piRootOf } from "./layout.ts";
+import { sanitize } from "./palette.ts";
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export type PeekPhase = "idle" | "thinking" | "done";
+
+export interface PeekState {
+	phase: PeekPhase;
+	tail: string;
+}
+
+export function createPeek(): PeekState {
+	return { phase: "idle", tail: "" };
+}
+
+/** Cumulative thinking/text of an assistant message's content parts. */
+export function collectParts(content: unknown): { thinking: string; text: string } {
+	let thinking = "";
+	let text = "";
+	if (!Array.isArray(content)) return { thinking, text };
+	for (const p of content as any[]) {
+		if (p?.type === "thinking") thinking += typeof p.thinking === "string" ? p.thinking : (p.text ?? "");
+		else if (p?.type === "text") text += p.text ?? "";
+	}
+	return { thinking, text };
+}
+
+/** Last non-empty line of the thinking text, whitespace-collapsed. */
+export function lastLine(thinking: string): string {
+	const lines = thinking.split("\n");
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const l = lines[i]!.replace(/\s+/g, " ").trim();
+		if (l) return l;
+	}
+	return "";
+}
+
+/**
+ * Phase machine: idle+thinking -> thinking; thinking+text -> done; done never restarts.
+ * Text without thinking leaves idle alone (nothing to peek at).
+ */
+export function reducePeek(prev: PeekState, parts: { thinking: string; text: string }): PeekState {
+	const tail = parts.thinking ? lastLine(parts.thinking) : prev.tail;
+	let phase = prev.phase;
+	if (parts.thinking && phase === "idle") phase = "thinking";
+	if (parts.text && phase === "thinking") phase = "done";
+	return { phase, tail };
+}
+
+/** Keep the end of `text` within `width` columns, prefixing "…" when clipped. */
+export function clipTail(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(text) <= width) return text;
+	const chars = [...text];
+	let out = "";
+	for (let i = chars.length - 1; i >= 0; i--) {
+		if (visibleWidth(`…${chars[i]}${out}`) > width) break;
+		out = chars[i] + out;
+	}
+	return `…${out}`;
+}
+
+export function peekLabel(state: PeekState, frame: number, width: number): string {
+	const w = Math.max(1, width);
+	if (state.phase === "thinking") {
+		const marker = `${SPINNER[frame % SPINNER.length]} thinking`;
+		const tail = sanitize(state.tail);
+		const room = w - visibleWidth(marker) - 1;
+		return truncateToWidth(tail && room > 4 ? `${marker} ${clipTail(tail, room)}` : marker, w, "…");
+	}
+	if (state.phase === "done") return truncateToWidth("✓ thought", w, "…");
+	return truncateToWidth("· thinking", w, "…");
+}
+
+interface LabelTarget {
+	setHiddenThinkingLabel(label: string): void;
+	updateContent(message: unknown, streaming?: boolean): void;
+	children: unknown[];
+}
+
+const isTarget = (v: any): v is LabelTarget =>
+	v && Array.isArray(v.children) && typeof v.setHiddenThinkingLabel === "function" && typeof v.updateContent === "function";
+
+/** Latest assistant message component in the TUI tree, or undefined. */
+export function findLatestAssistant(root: unknown): LabelTarget | undefined {
+	const stack: unknown[] = [root];
+	const seen = new Set<object>();
+	let latest: LabelTarget | undefined;
+	while (stack.length) {
+		const v = stack.pop() as any;
+		if (!v || typeof v !== "object" || seen.has(v)) continue;
+		seen.add(v);
+		if (isTarget(v)) latest = v;
+		// Layout nodes keep children in `children`; ScrollView keeps its content in `child`.
+		if (v.child) stack.push(v.child);
+		const kids = v.children;
+		if (Array.isArray(kids)) for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+	}
+	return latest;
+}
+
+/** Drives the peek label for the streaming message. */
+export class ThinkingPeek {
+	private state = createPeek();
+	private frame = 0;
+	private target: LabelTarget | undefined;
+	private active = false;
+
+	private readonly getTui: () => TUI | undefined;
+	private readonly width: () => number;
+
+	constructor(getTui: () => TUI | undefined, width: () => number) {
+		this.getTui = getTui;
+		this.width = width;
+	}
+
+	reset(): void {
+		this.state = createPeek();
+		this.target = undefined;
+	}
+
+	/** Feed an assistant message_update. Returns true when the label changed. */
+	update(message: any): void {
+		if (this.state.phase === "done") return;
+		const next = reducePeek(this.state, collectParts(message?.content));
+		if (next.phase === this.state.phase && next.tail === this.state.tail) return;
+		this.state = next;
+		if (next.phase === "thinking") this.frame++;
+		if (next.phase !== "idle") this.apply();
+	}
+
+	/** Assistant sub-message ended while still thinking: freeze the label. */
+	end(): void {
+		if (this.state.phase !== "thinking") return;
+		this.state = { ...this.state, phase: "done" };
+		this.apply();
+	}
+
+	private apply(): void {
+		const tui = this.getTui();
+		if (!tui) return;
+		this.target ??= findLatestAssistant(piRootOf(tui));
+		if (!this.target) return;
+		this.target.setHiddenThinkingLabel(peekLabel(this.state, this.frame, this.width()));
+		this.active = true;
+		tui.requestRender();
+	}
+
+	get isActive(): boolean {
+		return this.active;
+	}
+}

package/extensions/chassis/prompt-row.ts

@@ -0,0 +1,86 @@
+/**
+ * The agent and model row at the bottom of the prompt box:
+ *
+ *    󰚩 BUILD   Sonnet 4.5  Anthropic  medium
+ *   ^^^^^^^^^^^
+ *   a filled pill in the mode colour (brand primary for build, brand plan colour for plan) with the
+ *   mode's icon, then the model, the provider, and the thinking level in chassis's own colour for it.
+ *
+ * Pure functions over a theme, so the row can be tested without an editor. With a Nerd Font the pill
+ * caps are the Powerline round caps and the mode has an icon; without one the caps are half blocks
+ * and the pill is just the label (icons.ts).
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { backgroundAnsi, type Color, foregroundAnsi, truncateToWidth } from "@earendil-works/pi-tui";
+import { icon, withIcon } from "./icons.ts";
+import { brandColor, isLight, paint, readableOn, surfaceColor, toColor } from "./palette.ts";
+
+export type Mode = "build" | "plan";
+
+/** The mode's icon in the current set: a robot for build and an eye for plan, or none. */
+export const modeIcon = (mode: Mode): string => icon(mode === "plan" ? "modePlan" : "modeBuild");
+
+/** The mode's colour as a parsed colour: the brand plan colour for plan, the primary for build. */
+export const modeColorValue = (mode: Mode) => brandColor(mode === "plan" ? "plan" : "primary");
+
+/** The pill's text: the dark panel shade on a dark theme, near-black on a light one, so it reads on the mode colour either way. */
+const pillInk = (theme: Theme): Color => (isLight(theme) ? toColor("#121212") : surfaceColor(theme, "panel"));
+
+/** A filled pill with round caps: "<icon> <LABEL> " in dark text on the mode colour. The left cap is already a curve, so the icon sits right against it. */
+export function modePill(theme: Theme, mode: Mode): string {
+	const color = modeColorValue(mode);
+	const depth = theme.getColorMode();
+	const label = withIcon(modeIcon(mode), mode === "plan" ? "PLAN" : "BUILD");
+	// The row is shaded on the element surface, so the caps only set a foreground; the body sets
+	// both, and ends with \x1b[49m, which shade() turns back into the surface colour.
+	const body = `${backgroundAnsi(color, depth)}${foregroundAnsi(pillInk(theme), depth)}\x1b[1m${label} \x1b[22m\x1b[39m\x1b[49m`;
+	return `${paint(theme, color, icon("capLeft"))}${body}${paint(theme, color, icon("capRight"))}`;
+}
+
+/**
+ * One colour per thinking level, chassis's own and the same under every theme and brand. It warms
+ * up with the effort: grey when off, then blue, violet and amber, and red only at the top, so a red
+ * label means the most expensive setting and nothing else. Bright enough for the dark panel shades;
+ * under a light theme thinkingLabel darkens the same hues.
+ */
+export const THINKING_COLORS: Readonly<Record<string, string>> = {
+	off: "#6E716E",
+	minimal: "#8E9398",
+	low: "#7FA6C9",
+	medium: "#5F9BE0",
+	high: "#A48BE0",
+	xhigh: "#E0A94F",
+	max: "#F0505F",
+};
+
+/**
+ * The thinking level's name in its colour from THINKING_COLORS; nothing for a model that does not
+ * reason. An unknown level takes the "off" colour.
+ */
+export function thinkingLabel(theme: Theme, level: string | undefined): string {
+	if (!level) return "";
+	const color = toColor(THINKING_COLORS[level] ?? THINKING_COLORS.off!);
+	// Chosen for the dark panels; on a light theme the same hue is darkened until it can be read.
+	return paint(theme, isLight(theme) ? readableOn(color, surfaceColor(theme, "element")) : color, level);
+}
+
+export interface ModelParts {
+	/** Model name as pi reports it, for example "Claude Sonnet 5.5". */
+	model: string;
+	provider?: string;
+	/** Thinking level, when the model reasons. */
+	effort?: string;
+}
+
+/** The whole row, cut to `width` columns. */
+export function promptRow(theme: Theme, mode: Mode, parts: ModelParts, width: number): string {
+	const name = parts.model.replace(/^Claude /, "");
+	const segments = [
+		modePill(theme, mode),
+		theme.fg("text", name),
+		...(parts.provider ? [theme.fg("muted", parts.provider)] : []),
+		thinkingLabel(theme, parts.effort),
+	].filter(Boolean);
+	return truncateToWidth(segments.join("  "), width, "…");
+}

package/extensions/chassis/provider-view.ts

@@ -0,0 +1,118 @@
+/**
+ * Turns a provider status spec (provider.ts) into what the sidebar and footer draw.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { WidgetColor } from "./api.ts";
+import { sanitizeKeepColor } from "./palette.ts";
+import { getProviderStatus, providerStatusKeys, type ProviderStatusSpec } from "./provider.ts";
+
+export interface ResolvedMeter {
+	label: string;
+	percent?: number;
+	detail?: string;
+	color?: WidgetColor;
+	/** The status's own colour escape, for a `statusKey` meter whose provider colours it. */
+	sgr?: string;
+}
+
+const stripSgr = (s: string) => s.replace(/\x1b\[[0-9;:]*m/g, "");
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Drop a leading glyph and the provider's name or id from a status, leaving "71%" or "71% of plan". */
+function withoutLabel(text: string, names: string[]): string {
+	let out = text.replace(/^[^\p{L}\p{N}]+/u, "");
+	for (const n of names) {
+		if (!n) continue;
+		const m = out.match(new RegExp(`^${escapeRe(n)}\\b[\\s:·-]*`, "i"));
+		if (m) {
+			out = out.slice(m[0].length);
+			break;
+		}
+	}
+	return out.trim();
+}
+
+function namesOf(spec: ProviderStatusSpec): string[] {
+	return [spec.name ?? "", ...(Array.isArray(spec.provider) ? spec.provider : [spec.provider])];
+}
+
+/** The bars for the provider section: the `statusKey` percentage first, then `meters`. */
+export function providerMeters(spec: ProviderStatusSpec, ctx: ExtensionContext, statuses: ReadonlyMap<string, string>): ResolvedMeter[] {
+	const out: ResolvedMeter[] = [];
+	const raw = spec.statusKey ? statuses.get(spec.statusKey) : undefined;
+	if (raw) {
+		const clean = sanitizeKeepColor(raw);
+		const pct = Number.parseFloat(withoutLabel(stripSgr(clean), namesOf(spec)).match(/\d+(?:\.\d+)?/)?.[0] ?? "");
+		if (Number.isFinite(pct)) out.push({ label: spec.label ?? "Plan", percent: pct, sgr: clean.match(/\x1b\[[0-9;:]*m/)?.[0] });
+	}
+	if (spec.meters) {
+		try {
+			for (const m of spec.meters(ctx) ?? []) out.push({ ...m, percent: Number.isFinite(m.percent) ? m.percent : undefined });
+		} catch {
+			// a broken provider hook must not take the sidebar down
+		}
+	}
+	return out;
+}
+
+/** Short text for the footer, next to the context: the status without its label (keeping its colour), or the bars as "Plan 71%". */
+export function providerFooterText(spec: ProviderStatusSpec, ctx: ExtensionContext, statuses: ReadonlyMap<string, string>): string {
+	const raw = spec.statusKey ? statuses.get(spec.statusKey) : undefined;
+	if (raw) {
+		const clean = sanitizeKeepColor(raw);
+		const text = withoutLabel(stripSgr(clean), namesOf(spec));
+		const sgr = clean.match(/\x1b\[[0-9;:]*m/)?.[0];
+		return sgr && text ? `${sgr}${text}\x1b[39m` : text;
+	}
+	return providerMeters(spec, ctx, statuses)
+		.filter((m) => m.percent !== undefined)
+		.map((m) => `${m.label} ${Math.round(m.percent!)}%`)
+		.join(" ");
+}
+
+/**
+ * Heading for the provider: the spec's `name`, else the name the provider registered with pi
+ * (`ctx.modelRegistry.getProviderDisplayName`), else the id with a capital letter. A provider's
+ * name is often its login dialog title, such as "Acme (Builder ID / Google / GitHub)", so a
+ * trailing parenthetical is dropped to leave "Acme".
+ */
+export function providerDisplayName(ctx: ExtensionContext | undefined, spec?: ProviderStatusSpec): string {
+	if (spec?.name) return spec.name;
+	const id = ctx?.model?.provider;
+	if (!id) return "no provider";
+	let name: string | undefined;
+	try {
+		name = ctx?.modelRegistry?.getProviderDisplayName(id);
+	} catch {
+		// stale ctx or an older pi
+	}
+	const short = name?.replace(/\s*\([^)]*\)\s*$/, "").trim();
+	return short && short !== id ? short : id.replace(/^./, (x) => x.toUpperCase());
+}
+
+/** The implicit spec for a provider that follows the `<provider>-usage` status convention. */
+const conventional = (provider: string): ProviderStatusSpec => ({ provider, statusKey: `${provider}-usage` });
+
+/**
+ * The spec in effect for the active provider: the registered one, else, when the provider publishes
+ * a `<provider>-usage` status that carries a percentage (a convention some provider extensions follow), one built from
+ * that convention, so a provider needs no registration just to get its Plan bar. A status without a
+ * number is left alone and shows in the generic status list.
+ */
+export function activeProviderStatus(ctx: ExtensionContext | undefined, statuses: ReadonlyMap<string, string>): ProviderStatusSpec | undefined {
+	const id = ctx?.model?.provider;
+	if (!id) return undefined;
+	const registered = getProviderStatus(id);
+	if (registered) return registered;
+	const spec = conventional(id);
+	return providerMeters(spec, ctx!, statuses).length ? spec : undefined;
+}
+
+/** Status keys that belong to the provider section, so the generic status lists skip them. */
+export function claimedProviderKeys(ctx: ExtensionContext | undefined, statuses: ReadonlyMap<string, string>): Set<string> {
+	const keys = providerStatusKeys();
+	const spec = activeProviderStatus(ctx, statuses);
+	if (spec?.statusKey) keys.add(spec.statusKey);
+	return keys;
+}