pi-dev-team 0.2.0

package/extensions/dev-team/lib/usage-command.ts

@@ -0,0 +1,107 @@
+/**
+ * `/dev-team usage [session|month]`: opens the usage overlay, or prints the plain-text summary
+ * when no overlay can be shown. The overlay is out of reach without a UI (print mode) and in RPC mode,
+ * where `ui.custom()` is a stub that resolves without ever calling the factory, so "the factory never
+ * ran" is the signal to fall back to text. A `ui.custom()` that rejects falls back to text too.
+ */
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type SpendRun, sessionEntries, sessionSpend } from "./session-spend.ts";
+import { monthSnapshot, usageBreakdown } from "./usage-breakdown.ts";
+import { loadSpendHistory, sessionRoot } from "./usage-history.ts";
+import { usageMonthStart } from "./ai-credits.ts";
+import type { UsageStyle } from "./usage-render.ts";
+import { openUsage, type Scope, type Transition } from "./usage-state.ts";
+import { errorReason, loadFailedMessage, usageSummary } from "./usage-text.ts";
+import { OVERLAY_HEIGHT_PERCENT, UsageView } from "./usage-view.ts";
+
+export interface UsageDeps {
+	now(): Date;
+	loadHistory: typeof loadSpendHistory;
+	/** Shows text to the user (a notification with a UI, stdout without). */
+	emit(text: string): void;
+}
+
+export const USAGE_SYNTAX = "Usage: /dev-team usage [session|month]";
+
+const SCOPE_ARGS: ReadonlyMap<string, Scope> = new Map([
+	["", "session"],
+	["session", "session"],
+	["month", "month"],
+]);
+
+/** The scope `/dev-team usage <args>` asks for (this session when none is given), or the usage message for an argument it does not know. */
+export function parseUsageArgs(args: string): { scope: Scope } | { error: string } {
+	const scope = SCOPE_ARGS.get(args.trim().toLowerCase());
+	return scope ? { scope } : { error: USAGE_SYNTAX };
+}
+
+const sessionRunsOf = (ctx: ExtensionContext): SpendRun[] => [...sessionSpend(sessionEntries(ctx))];
+const sessionRootOf = (ctx: ExtensionContext): string => sessionRoot(ctx.sessionManager.getSessionDir());
+
+/** A distinct colour per split segment slot, one per glyph in SPLIT_GLYPHS (usage-split-bar.ts), which tell the slots apart without colour. */
+const SEGMENT_COLORS = ["accent", "success", "warning", "muted"] as const;
+
+/** pi theme tokens for the overlay: accent bars, a distinct colour per split segment, muted secondary text. */
+function themeStyle(theme: Theme): UsageStyle {
+	return {
+		title: (text) => theme.bold(text),
+		error: (text) => theme.fg("error", text),
+		bar: (text) => theme.fg("accent", text),
+		muted: (text) => theme.fg("muted", text),
+		segment: (slot, text) => theme.fg(SEGMENT_COLORS[slot] ?? "muted", text),
+	};
+}
+
+/** The text summary: this month is read from every saved session (no progress to show), a failed read is reported, never thrown. */
+async function printSummary(ctx: ExtensionContext, scope: Scope, deps: UsageDeps): Promise<void> {
+	const now = deps.now();
+	if (scope === "session") {
+		deps.emit(usageSummary({ scope, breakdown: usageBreakdown(sessionRunsOf(ctx)), now }));
+		return;
+	}
+	try {
+		const history = await deps.loadHistory({ root: sessionRootOf(ctx), since: usageMonthStart(now) });
+		const snapshot = monthSnapshot(history, deps.now());
+		deps.emit(usageSummary({ scope, breakdown: snapshot.breakdown, now, month: snapshot }));
+	} catch (err) {
+		deps.emit(loadFailedMessage(errorReason(err)));
+	}
+}
+
+/** Shows the overlay; false when it could not be shown (the factory never ran, or `ui.custom()` rejected). */
+async function showOverlay(ctx: ExtensionContext, initial: Transition, deps: UsageDeps): Promise<boolean> {
+	let factoryRan = false;
+	try {
+		await ctx.ui.custom<void>(
+			(tui, theme, _keybindings, done) => {
+				factoryRan = true;
+				return new UsageView(
+					{
+						sessionRuns: () => sessionRunsOf(ctx),
+						now: deps.now,
+						terminalRows: () => tui.terminal.rows,
+						style: themeStyle(theme),
+						requestRender: () => tui.requestRender(),
+						close: () => done(),
+						loadHistory: (options) => deps.loadHistory({ root: sessionRootOf(ctx), ...options }),
+					},
+					initial,
+				);
+			},
+			{ overlay: true, overlayOptions: { maxHeight: `${OVERLAY_HEIGHT_PERCENT}%` } },
+		);
+	} catch {
+		return false;
+	}
+	return factoryRan;
+}
+
+export async function runUsage(ctx: ExtensionContext, args: string, deps: UsageDeps): Promise<void> {
+	const parsed = parseUsageArgs(args);
+	if ("error" in parsed) {
+		deps.emit(parsed.error);
+		return;
+	}
+	if (ctx.hasUI && (await showOverlay(ctx, openUsage(parsed.scope), deps))) return;
+	await printSummary(ctx, parsed.scope, deps);
+}

package/extensions/dev-team/lib/usage-history.ts

@@ -0,0 +1,203 @@
+/**
+ * Timestamped runs of spend loaded from every saved pi session file, for the "This month" scope of
+ * /dev-team usage. All providers are loaded; grouping them is usage-breakdown's job.
+ * Reads are stat-first and async so a large session history does not stall the TUI. Spend is
+ * classified by sessionSpendByEntry() (session-spend.ts), the same walk the status line uses, so both
+ * views agree on what a run is.
+ */
+import { createReadStream, type Dirent } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import * as path from "node:path";
+import { createInterface } from "node:readline";
+import { sessionSpendByEntry, type SpendRun } from "./session-spend.ts";
+
+
+/** One run of spend, with when its session entry was written (the entry's ISO 8601 `timestamp`, as stored). */
+export interface SpendRecord {
+	timestamp: string;
+	run: SpendRun;
+}
+
+export interface SpendHistory {
+	records: SpendRecord[];
+	/** Session files that could not be read. Files skipped for being too old, or gone before they were read, are not counted. */
+	unreadable: number;
+	/** True when the load was cancelled; `records` then hold only what was read before that. */
+	aborted: boolean;
+}
+
+/** pi names a project's session folder `--<encoded cwd>--`. */
+const PROJECT_DIR = /^--.+--$/;
+
+/**
+ * The folder every project's sessions live under: the parent of a session's own `--<cwd>--` folder,
+ * or the folder itself when a custom session dir keeps its files flat.
+ */
+export function sessionRoot(sessionDir: string): string {
+	return PROJECT_DIR.test(path.basename(sessionDir)) ? path.dirname(sessionDir) : sessionDir;
+}
+
+const SESSION_FILE_EXTENSION = ".jsonl";
+
+const isNotFound = (err: unknown): boolean => (err as { code?: string } | undefined)?.code === "ENOENT";
+
+/** By code unit, so the order that decides which copy of a shared entry wins is the same on every machine and locale. */
+const sortedByName = (dirents: readonly Dirent[]): Dirent[] => [...dirents].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+/** The session files among a folder's dirents, in name order. */
+const sessionFilesIn = (dir: string, dirents: readonly Dirent[]): string[] =>
+	sortedByName(dirents).filter((dirent) => dirent.isFile() && dirent.name.endsWith(SESSION_FILE_EXTENSION)).map((dirent) => path.join(dir, dirent.name));
+
+/**
+ * Session files directly under the root (`<root>/*.jsonl`, a flat custom session dir) or one folder
+ * down (`<root>/<project>/*.jsonl`, pi's default layout), and nothing deeper: another extension keeps
+ * its own `<session>/<hash>/run-N/session.jsonl` transcripts under the same root, and those are not
+ * this session history. A missing root is no history; any other failure to list it is thrown. A project
+ * folder that cannot be listed counts as one unreadable file, since its sessions are unknown.
+ */
+async function listSessionFiles(root: string): Promise<{ files: string[]; unlistable: number }> {
+	const files: string[] = [];
+	let unlistable = 0;
+	let rootDirents;
+	try {
+		rootDirents = await readdir(root, { withFileTypes: true });
+	} catch (err) {
+		if (isNotFound(err)) return { files, unlistable };
+		throw err;
+	}
+	files.push(...sessionFilesIn(root, rootDirents));
+	for (const folder of sortedByName(rootDirents).filter((dirent) => dirent.isDirectory())) {
+		const dir = path.join(root, folder.name);
+		try {
+			files.push(...sessionFilesIn(dir, await readdir(dir, { withFileTypes: true })));
+		} catch (err) {
+			if (!isNotFound(err)) unlistable++;
+		}
+	}
+	return { files, unlistable };
+}
+
+/**
+ * A line's JSON object, or undefined for a blank line, a truncated last line or any other line that is
+ * not an entry. pi's own parseSessionEntries is not used: pi exports it for its tests only, and it keeps
+ * any parsed value, where a line that is not an object (`null`, `[1]`, `7`) cannot be an entry and is
+ * dropped here.
+ */
+function parseEntry(line: string): Record<string, unknown> | undefined {
+	if (!line.trim()) return undefined;
+	try {
+		const value: unknown = JSON.parse(line);
+		return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * A file's entries, read line by line so the file's text is never held whole; only the parsed entries
+ * are, since a compaction's model depends on entries before it. `signal` is checked between lines, and
+ * the stream is destroyed however the read ends. Undefined when aborted partway: the file is then
+ * unfinished and must add nothing. Throws when the file cannot be opened or read.
+ */
+async function readEntries(file: string, signal: AbortSignal | undefined): Promise<Record<string, unknown>[] | undefined> {
+	const entries: Record<string, unknown>[] = [];
+	const input = createReadStream(file, { encoding: "utf8" });
+	const lines = createInterface({ input, crlfDelay: Infinity });
+	try {
+		for await (const line of lines) {
+			if (signal?.aborted) return undefined;
+			const entry = parseEntry(line);
+			if (entry) entries.push(entry);
+		}
+	} finally {
+		lines.close();
+		input.destroy();
+	}
+	return entries;
+}
+
+/**
+ * Identifies an entry across session files: a fork or clone copies entries verbatim, id and timestamp
+ * included, so the same pair in two files is one piece of spend. Undefined for an entry without an id.
+ */
+const entryKey = (entry: Record<string, unknown>): string | undefined => (typeof entry.id === "string" ? `${entry.id}|${entry.timestamp}` : undefined);
+
+/**
+ * One session file's runs of spend since `since`, leaving out entries whose key is in `seenKeys` (kept
+ * from earlier files) or that repeat an earlier entry of this file, and the keys of the entries it
+ * kept. Throws when the file cannot be read or holds an entry sessionSpendByEntry() cannot make sense
+ * of; nothing partial is returned, so an unreadable file adds no records and claims no keys. Undefined
+ * when `signal` aborted the read partway.
+ */
+async function readRecords(file: string, since: Date, seenKeys: ReadonlySet<string>, signal: AbortSignal | undefined): Promise<{ records: SpendRecord[]; entryKeys: string[] } | undefined> {
+	const entries = await readEntries(file, signal);
+	if (!entries) return undefined;
+	const records: SpendRecord[] = [];
+	const entryKeys = new Set<string>();
+	for (const { entry, runs } of sessionSpendByEntry(entries)) {
+		const { timestamp } = entry;
+		// An entry with no usable time cannot be placed in the month, so it is left out.
+		if (typeof timestamp !== "string" || !(Date.parse(timestamp) >= since.getTime())) continue;
+		const key = entryKey(entry);
+		if (runs.length === 0 || (key !== undefined && (seenKeys.has(key) || entryKeys.has(key)))) continue;
+		if (key !== undefined) entryKeys.add(key);
+		for (const run of runs) records.push({ timestamp, run });
+	}
+	return { records, entryKeys: [...entryKeys] };
+}
+
+export interface LoadOptions {
+	/** The folder holding the project session folders (see sessionRoot). */
+	root: string;
+	/** Entries stamped before this are left out. */
+	since: Date;
+	/**
+	 * Called after each file that was read (or failed to be), over the files modified since `since`.
+	 * An error it throws is swallowed: progress display must not be able to fail the load.
+	 */
+	onProgress?: (done: number, total: number) => void;
+	/**
+	 * Stops the load, between files and between a file's lines; the result is then `aborted`, with the
+	 * files read whole so far (a file cut off partway adds nothing).
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * Every run of spend in the saved session files under `root`, with the time of the entry that spent
+ * it. A file last modified before `since` cannot hold an entry from after it, so it is never opened.
+ * An entry shared by several files (a fork or clone of a session) is counted once, from the first
+ * file read: root-level files by name, then each project folder's by name.
+ */
+export async function loadSpendHistory({ root, since, onProgress, signal }: LoadOptions): Promise<SpendHistory> {
+	const { files, unlistable } = await listSessionFiles(root);
+	const recentFiles: string[] = [];
+	let unreadable = unlistable;
+	for (const file of files) {
+		if (signal?.aborted) return { records: [], unreadable, aborted: true };
+		try {
+			if ((await stat(file)).mtimeMs >= since.getTime()) recentFiles.push(file);
+		} catch (err) {
+			if (!isNotFound(err)) unreadable++;
+		}
+	}
+	const records: SpendRecord[] = [];
+	const seenKeys = new Set<string>();
+	for (const [i, file] of recentFiles.entries()) {
+		if (signal?.aborted) return { records, unreadable, aborted: true };
+		try {
+			const fileResult = await readRecords(file, since, seenKeys, signal);
+			if (!fileResult) return { records, unreadable, aborted: true };
+			for (const record of fileResult.records) records.push(record);
+			for (const key of fileResult.entryKeys) seenKeys.add(key);
+		} catch (err) {
+			if (!isNotFound(err)) unreadable++;
+		}
+		try {
+			onProgress?.(i + 1, recentFiles.length);
+		} catch {
+			// a failing progress display must not fail the load
+		}
+	}
+	return { records, unreadable, aborted: false };
+}

package/extensions/dev-team/lib/usage-render.ts

@@ -0,0 +1,225 @@
+/**
+ * Renders the /dev-team usage overlay. renderUsage() turns the view's state plus the usage breakdown
+ * into the lines of the panel (header, split bars, ranked chart, footer), fitted to the terminal's width
+ * and height; it is pure (colour comes from the injected style), so tests drive it without pi. The
+ * component that holds the state and reacts to keys is UsageView (usage-view.ts).
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { formatShare, formatUsd, hasUsage, type MonthSnapshot, type UsageBreakdown, type UsageRow } from "./usage-breakdown.ts";
+import { cutToWidth } from "./terminal-text.ts";
+import { barChartLines, type ChartStyle } from "./usage-chart.ts";
+import { type SplitBarOptions, type SplitStyle, splitBarLines } from "./usage-split-bar.ts";
+import type { UsageState } from "./usage-state.ts";
+import {
+	asOfLabel,
+	CHART_FORMAT,
+	emptyUsageMessage,
+	loadFailedMessage,
+	noSubagentUsageMessage,
+	pressSHint,
+	READING_SESSIONS,
+	SCOPE_NOUN,
+	SCOPE_TITLE,
+	SEPARATOR,
+	scopeHeading,
+	splitSections,
+	totalHeaderParts,
+	unreadableFilesNote,
+	VIEW_TITLE,
+	viewRows,
+	wantedColumns,
+} from "./usage-text.ts";
+
+export interface UsageStyle extends ChartStyle, SplitStyle {
+	/** The header line. */
+	title(text: string): string;
+	/** The load failure message. */
+	error(text: string): string;
+}
+
+export interface UsageViewModel {
+	state: UsageState;
+	/** This session's breakdown. */
+	session: UsageBreakdown;
+	/** This month's, once loaded. */
+	month?: MonthSnapshot;
+	now: Date;
+}
+
+export interface RenderOptions {
+	width: number;
+	/** Most lines the panel may take. */
+	height: number;
+	style: UsageStyle;
+}
+
+/** The breakdown the state is showing, or undefined while it is not known (loading, failed). */
+function shownBreakdown(viewModel: UsageViewModel): UsageBreakdown | undefined {
+	if (viewModel.state.scope === "session") return viewModel.session;
+	return viewModel.state.load.kind === "ready" ? viewModel.month?.breakdown : undefined;
+}
+
+/**
+ * The header from most to least detailed: the snapshot time goes first, then the dates, then the
+ * AI credits, so a narrow terminal keeps the scope, the view and the USD total.
+ */
+function headerCandidates(viewModel: UsageViewModel): string[] {
+	const { scope, view } = viewModel.state;
+	const breakdown = shownBreakdown(viewModel);
+	const totals = breakdown ? totalHeaderParts(breakdown.total) : [];
+	const [usdPart] = totals;
+	const usdOnly = usdPart ? [usdPart] : [];
+	const asOfParts = scope === "month" && breakdown && viewModel.month ? [asOfLabel(viewModel.month.loadedAt)] : [];
+	const join = (scopeText: string, shownTotals: readonly string[], ...more: string[]) => [scopeText, VIEW_TITLE[view], ...shownTotals, ...more].join(SEPARATOR);
+	const heading = scopeHeading(scope, viewModel.now);
+	return [join(heading, totals, ...asOfParts), join(heading, totals), join(SCOPE_TITLE[scope], totals), join(SCOPE_TITLE[scope], usdOnly)];
+}
+
+/** The key hints from most to least detailed: hints drop from the left, so "Esc close" is the last to go. */
+function footerCandidates(state: UsageState): string[] {
+	const otherScopeNoun = SCOPE_NOUN[state.scope === "session" ? "month" : "session"];
+	let hints = ["Tab view", `s ${otherScopeNoun}`, "Esc close"];
+	if (state.load.kind === "error") hints = ["s back", "Esc close"];
+	else if (state.load.kind === "loading") hints = ["Tab view", "s cancel", "Esc close"];
+	return hints.map((_, i) => hints.slice(i).join(SEPARATOR));
+}
+
+/** The first candidate that fits `width`, else the last one cut to it. */
+function fitLine(candidates: readonly string[], width: number): string {
+	return candidates.find((c) => visibleWidth(c) <= width) ?? cutToWidth(candidates.at(-1) ?? "", width);
+}
+
+/** Text that fills the chart area in place of a chart. */
+interface Message {
+	text: string;
+	tone: "plain" | "error";
+}
+
+function loadingMessage(load: UsageState["load"]): string {
+	return load.kind === "loading" && load.progress ? `${READING_SESSIONS} ${load.progress.done}/${load.progress.total} files` : READING_SESSIONS;
+}
+
+/** What replaces the chart when there is none to draw; undefined when the view has rows. */
+function bodyMessage(viewModel: UsageViewModel, breakdown: UsageBreakdown | undefined): Message | undefined {
+	const { state } = viewModel;
+	if (state.load.kind === "loading") return { text: loadingMessage(state.load), tone: "plain" };
+	if (state.load.kind === "error") return { text: loadFailedMessage(state.load.reason), tone: "error" };
+	if (!breakdown || !hasUsage(breakdown.total)) return { text: `${emptyUsageMessage(state.scope)}${pressSHint(state.scope)}`, tone: "plain" };
+	if (state.view === "agent" && breakdown.byAgent.length === 0) return { text: noSubagentUsageMessage(state.scope), tone: "plain" };
+	return undefined;
+}
+
+function footnoteText(viewModel: UsageViewModel): string | undefined {
+	const { state, month } = viewModel;
+	const unreadable = state.scope === "month" && state.load.kind === "ready" ? (month?.unreadable ?? 0) : 0;
+	return unreadableFilesNote(unreadable);
+}
+
+/** One split bar's lines: the bar, then its legend lines. */
+interface SplitBlock {
+	bar: string;
+	legend: string[];
+}
+
+/** The split bars of splitSections(): providers (legend gives each share), then threads (legend gives each USD). */
+function splitBlocks(breakdown: UsageBreakdown, options: Omit<SplitBarOptions, "formatValue">): SplitBlock[] {
+	return splitSections(breakdown).flatMap((section): SplitBlock[] => {
+		const formatValue = (usd: number, share: number) => (section.legend === "share" ? formatShare(share) : formatUsd(usd));
+		const lines = splitBarLines(
+			section.parts.map((p) => ({ label: p.label, amount: p.usd })),
+			{ ...options, formatValue },
+		);
+		return lines.length ? [{ bar: lines[0], legend: lines.slice(1) }] : [];
+	});
+}
+
+/** `count` split lines at most: every bar first, then legend lines block by block; each block stays in order. */
+function fitSplitLines(blocks: readonly SplitBlock[], count: number): string[] {
+	let legendBudget = Math.max(0, count - blocks.length);
+	return blocks.slice(0, count).flatMap((block) => {
+		const legend = block.legend.slice(0, legendBudget);
+		legendBudget -= legend.length;
+		return [block.bar, ...legend];
+	});
+}
+
+/** What the panel would like to show, in lines. */
+interface LayoutRequest {
+	splitLineCount: number;
+	/** The split bars without their legends: what is left when the legends give way. */
+	splitBarCount: number;
+	hasFootnote: boolean;
+	chartRowCount: number;
+}
+
+interface Layout {
+	/** Blank lines between header, split bar, chart and footer. */
+	hasGaps: boolean;
+	/** Split bar lines kept (the bar first, then its legend). */
+	splitLineCount: number;
+	hasFootnote: boolean;
+	chartRowCount: number;
+}
+
+const PINNED_LINES = 2;
+const FOOTNOTE_LINES = 1;
+/** Chart rows worth keeping over the extras before the extras start to go. */
+const MIN_CHART_ROWS = 3;
+/** Blank lines after the header and before the footer. */
+const OUTER_GAP_LINES = 2;
+/** The blank line after the split bar, when there is one. */
+const SPLIT_GAP_LINES = 1;
+
+/** The blank lines kept between header, split bar (when there is one), chart and footer. */
+const gapLineCount = (hasSplit: boolean) => OUTER_GAP_LINES + (hasSplit ? SPLIT_GAP_LINES : 0);
+
+/**
+ * Decides which lines are pinned and which flex for `height`. The header and footer always stay; the
+ * rest give way in order (blank gaps, footnote, split legends, split bars) until the chart gets
+ * MIN_CHART_ROWS rows or what it asked for, whichever is fewer. What is left goes to the chart.
+ */
+function planLayout(height: number, request: LayoutRequest): Layout {
+	const free = Math.max(0, height - PINNED_LINES);
+	const { splitLineCount, hasFootnote } = request;
+	const options: Layout[] = [
+		{ hasGaps: true, splitLineCount, hasFootnote, chartRowCount: 0 },
+		{ hasGaps: false, splitLineCount, hasFootnote, chartRowCount: 0 },
+		{ hasGaps: false, splitLineCount, hasFootnote: false, chartRowCount: 0 },
+		{ hasGaps: false, splitLineCount: Math.min(request.splitBarCount, splitLineCount), hasFootnote: false, chartRowCount: 0 },
+		{ hasGaps: false, splitLineCount: 0, hasFootnote: false, chartRowCount: 0 },
+	];
+	const withChartRows = (o: Layout): Layout => ({
+		...o,
+		chartRowCount: Math.max(0, free - (o.hasGaps ? gapLineCount(splitLineCount > 0) : 0) - o.splitLineCount - (o.hasFootnote ? FOOTNOTE_LINES : 0)),
+	});
+	const sized = options.map(withChartRows);
+	return sized.find((o) => o.chartRowCount >= Math.min(request.chartRowCount, MIN_CHART_ROWS)) ?? sized[sized.length - 1];
+}
+
+export function renderUsage(viewModel: UsageViewModel, { width, height, style }: RenderOptions): string[] {
+	const breakdown = shownBreakdown(viewModel);
+	const message = bodyMessage(viewModel, breakdown);
+	// The split bars show whenever there is spend to split, even when the view's own chart is empty.
+	const showSplit = !!breakdown && hasUsage(breakdown.total) && viewModel.state.load.kind !== "loading";
+	const blocks = showSplit ? splitBlocks(breakdown, { width, style }) : [];
+	const splitLineCount = blocks.reduce((sum, b) => sum + 1 + b.legend.length, 0);
+	const footnote = footnoteText(viewModel);
+	const rankedRows: UsageRow[] = breakdown ? viewRows(viewModel.state.view, breakdown) : [];
+	const plan = planLayout(height, { splitLineCount, splitBarCount: blocks.length, hasFootnote: !!footnote, chartRowCount: message ? 1 : rankedRows.length });
+
+	const splitLines = fitSplitLines(blocks, plan.splitLineCount);
+	const paint = message?.tone === "error" ? style.error : (text: string) => text;
+	const body = message
+		? plan.chartRowCount > 0 ? [paint(cutToWidth(message.text, width))] : []
+		: barChartLines(rankedRows, { width, maxRows: plan.chartRowCount, format: CHART_FORMAT, wantedColumns: wantedColumns(rankedRows), style });
+	const gapLines = plan.hasGaps ? [""] : [];
+	return [
+		style.title(fitLine(headerCandidates(viewModel), width)),
+		...gapLines,
+		...(splitLines.length ? [...splitLines, ...gapLines] : []),
+		...body,
+		...(footnote && plan.hasFootnote ? [style.muted(cutToWidth(footnote, width))] : []),
+		...gapLines,
+		style.muted(fitLine(footerCandidates(viewModel.state), width)),
+	];
+}

package/extensions/dev-team/lib/usage-split-bar.ts

@@ -0,0 +1,127 @@
+/**
+ * A stacked split for the /dev-team usage overlay (splitBarLines): one bar cut into segments by
+ * amount, then a legend. The overlay draws two: threads (main, subagents, overhead) and providers.
+ * Segments keep the order the caller gives, and each input position has its own glyph (█ ▓ ▒ ░) and
+ * colour, so the split reads without colour. A part with no amount draws nothing but keeps its
+ * position, so a fixed list of parts (the threads) always draws the same part with the same glyph. When
+ * there are more parts than glyphs, the parts with an amount are drawn in order and those past the
+ * last glyph fold into one "other" segment. Like the bar
+ * chart (usage-chart.ts) it is pure string rendering: plain text is measured and cut first, then
+ * styled.
+ */
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { cutToWidth, toSingleLine } from "./terminal-text.ts";
+import { FULL_BLOCK } from "./usage-chart.ts";
+
+/** One input to the split bar: an amount, which becomes (part of) a segment. */
+export interface SplitPart {
+	label: string;
+	amount: number;
+}
+
+export interface SplitStyle {
+	/** Colours the glyphs of the segment in slot `slot` (0 to SPLIT_GLYPHS.length - 1). */
+	segment(slot: number, text: string): string;
+	/** De-emphasises the legend separators. */
+	muted(text: string): string;
+}
+
+export interface SplitBarOptions {
+	width: number;
+	/** The legend's text for a part's amount; `share` is its fraction of the bar's total. */
+	formatValue(amount: number, share: number): string;
+	style: SplitStyle;
+	/** Cap on the bar; it also never exceeds `width`. */
+	maxBarCells?: number;
+}
+
+/** The glyph of each segment slot; there are as many segments as glyphs at most. */
+export const SPLIT_GLYPHS: readonly string[] = [FULL_BLOCK, "▓", "▒", "░"];
+const OTHER_LABEL = "other";
+type Segment = { label: string; slot: number; amount: number };
+const MAX_SPLIT_BAR_CELLS = 40;
+const LEGEND_SEPARATOR = " · ";
+
+/**
+ * Splits `cells` across the segment weights by largest remainder, so the result always sums to
+ * `cells` (ties go to the earlier weight). A segment that would get no cell borrows one from the
+ * largest segment, so a small non-zero thread stays visible, as long as there are cells to go round.
+ */
+function allocateCells(weights: readonly number[], cells: number): number[] {
+	const sum = (numbers: readonly number[]) => numbers.reduce((total, n) => total + n, 0);
+	const total = sum(weights);
+	const ideal = weights.map((w) => (w * cells) / total);
+	const wholeCells = ideal.map(Math.floor);
+	const remainder = (i: number) => ideal[i] - wholeCells[i];
+	const indicesByRemainder = ideal.map((_, i) => i).sort((a, b) => remainder(b) - remainder(a) || a - b);
+	const leftover = cells - sum(wholeCells);
+	const gainsLeftover = new Set(indicesByRemainder.slice(0, leftover));
+	return keepVisible(wholeCells.map((n, i) => (gainsLeftover.has(i) ? n + 1 : n)));
+}
+
+/** Moves one cell from the largest segment to each empty one (while the largest has cells to spare). */
+function keepVisible(allocated: readonly number[]): number[] {
+	return allocated.reduce(
+		(segmentCells, _, i) => {
+			if (segmentCells[i] > 0) return segmentCells;
+			const largestIndex = segmentCells.indexOf(Math.max(...segmentCells));
+			if (segmentCells[largestIndex] < 2) return segmentCells;
+			return segmentCells.map((n, j) => (j === largestIndex ? n - 1 : j === i ? n + 1 : n));
+		},
+		[...allocated],
+	);
+}
+
+/** The parts with an amount, each in its slot: its input position, or its rank among them when the parts outnumber the glyphs. */
+function toSegments(parts: readonly SplitPart[]): Segment[] {
+	// Labels can come from session files, so they are made one line before they are measured.
+	const slotted = (part: SplitPart, slot: number): Segment => ({ label: toSingleLine(part.label), slot, amount: part.amount });
+	if (parts.length <= SPLIT_GLYPHS.length) return parts.map(slotted).filter((s) => s.amount > 0);
+	const positive = parts.filter((p) => p.amount > 0);
+	if (positive.length <= SPLIT_GLYPHS.length) return positive.map(slotted);
+	const kept = positive.slice(0, SPLIT_GLYPHS.length - 1);
+	const other = { label: OTHER_LABEL, amount: positive.slice(kept.length).reduce((sum, p) => sum + p.amount, 0) };
+	return [...kept, other].map(slotted);
+}
+
+/** A bar split into segments by amount, in the given order, then a legend naming each with its value. */
+export function splitBarLines(parts: readonly SplitPart[], { width, formatValue, style, maxBarCells = MAX_SPLIT_BAR_CELLS }: SplitBarOptions): string[] {
+	const segments = toSegments(parts);
+	if (!segments.length) return [];
+
+	const segmentCells = allocateCells(segments.map((s) => s.amount), Math.max(0, Math.min(width, maxBarCells)));
+	const bar = segments.map((s, i) => style.segment(s.slot, SPLIT_GLYPHS[s.slot].repeat(segmentCells[i]))).join("");
+	return [bar, ...legendLines(segments, { width, formatValue, style })];
+}
+
+/**
+ * The legend ("█ main $0.30 · ▓ subagents $0.60"), packed onto as few lines as fit `width`. An entry
+ * never splits across lines; one wider than `width` on its own is cut to it. Each entry is cut as
+ * plain text, then its glyph is styled.
+ */
+function legendLines(
+	segments: readonly Segment[],
+	{ width, formatValue, style }: Pick<SplitBarOptions, "width" | "formatValue" | "style">,
+): string[] {
+	const separatorWidth = visibleWidth(LEGEND_SEPARATOR);
+	const total = segments.reduce((sum, s) => sum + s.amount, 0);
+	const lines: string[] = [];
+	let line = "";
+	let lineWidth = 0;
+	for (const s of segments) {
+		const glyph = SPLIT_GLYPHS[s.slot];
+		const plain = cutToWidth(`${glyph} ${s.label} ${formatValue(s.amount, s.amount / total)}`, width);
+		const entry = plain && style.segment(s.slot, plain.slice(0, glyph.length)) + plain.slice(glyph.length);
+		const entryWidth = visibleWidth(plain);
+		if (line && lineWidth + separatorWidth + entryWidth <= width) {
+			line += style.muted(LEGEND_SEPARATOR) + entry;
+			lineWidth += separatorWidth + entryWidth;
+			continue;
+		}
+		if (line) lines.push(line);
+		line = entry;
+		lineWidth = entryWidth;
+	}
+	lines.push(line);
+	return lines;
+}