pi-legion 0.16.0 → 2.0.0

package/src/tui/viz/canvas.ts

@@ -0,0 +1,119 @@
+/** Tiny cell grid: every cell is one terminal column wide, so widths are exact. */
+
+import { ROLE_COLOR_PREFIX, resolveRolePalette, type VizTheme } from "./palette.ts";
+
+export interface Cell {
+	ch: string;
+	color?: string;
+	bold?: boolean;
+	inverse?: boolean;
+}
+
+export class Canvas {
+	readonly width: number;
+	readonly height: number;
+	readonly cells: Cell[][];
+
+	constructor(width: number, height: number) {
+		this.width = Math.max(0, Math.floor(width));
+		this.height = Math.max(0, Math.floor(height));
+		this.cells = Array.from({ length: this.height }, () =>
+			Array.from({ length: this.width }, () => ({ ch: " " }) as Cell),
+		);
+	}
+
+	get(x: number, y: number): Cell | undefined {
+		return this.cells[y]?.[x];
+	}
+
+	set(x: number, y: number, ch: string, color?: string, style: { bold?: boolean; inverse?: boolean } = {}): void {
+		const row = this.cells[y];
+		if (!row || x < 0 || x >= this.width) return;
+		row[x] = { ch: sanitizeChar(ch), color, ...style };
+	}
+
+	/** Write text clipped to [x, maxX). Returns the column after the last written cell. */
+	text(x: number, y: number, value: string, color?: string, style: { bold?: boolean; inverse?: boolean; maxX?: number } = {}): number {
+		const limit = Math.min(this.width, style.maxX ?? this.width);
+		let col = x;
+		for (const ch of Array.from(value)) {
+			if (col >= limit) break;
+			if (col >= 0) this.set(col, y, ch, color, style);
+			col++;
+		}
+		return col;
+	}
+
+	/** Agent types referenced by deferred `role:` colors in this canvas. */
+	roles(): Set<string> {
+		const roles = new Set<string>();
+		for (const row of this.cells) for (const cell of row) {
+			if (cell.color?.startsWith(ROLE_COLOR_PREFIX)) roles.add(cell.color.slice(ROLE_COLOR_PREFIX.length));
+		}
+		return roles;
+	}
+
+	toLines(theme: VizTheme, palette = resolveRolePalette(theme, this.roles())): string[] {
+		const resolve = (color: string | undefined): string | undefined =>
+			color?.startsWith(ROLE_COLOR_PREFIX) ? palette.get(color.slice(ROLE_COLOR_PREFIX.length)) ?? "text" : color;
+		return this.cells.map((row) => renderRow(row.map((cell) => cell.color?.startsWith(ROLE_COLOR_PREFIX) ? { ...cell, color: resolve(cell.color) } : cell), theme));
+	}
+
+	toPlain(): string[] {
+		return this.cells.map((row) => row.map((cell) => cell.ch).join(""));
+	}
+}
+
+/** Keep cells single-width: wide/control characters become a placeholder. */
+export function sanitizeChar(ch: string): string {
+	if (ch.length === 0) return " ";
+	const code = ch.codePointAt(0)!;
+	if (code < 0x20 || (code >= 0x7f && code < 0xa0)) return " ";
+	if (isWide(code)) return "?";
+	return String.fromCodePoint(code);
+}
+
+function isWide(code: number): boolean {
+	return (
+		(code >= 0x1100 && code <= 0x115f) ||
+		(code >= 0x2e80 && code <= 0xa4cf) ||
+		(code >= 0xac00 && code <= 0xd7a3) ||
+		(code >= 0xf900 && code <= 0xfaff) ||
+		(code >= 0xfe30 && code <= 0xfe4f) ||
+		(code >= 0xff00 && code <= 0xff60) ||
+		(code >= 0xffe0 && code <= 0xffe6) ||
+		(code >= 0x1f300 && code <= 0x1faff) ||
+		(code >= 0x20000 && code <= 0x3fffd)
+	);
+}
+
+/** Truncate plain text to `width` single-width cells with an ellipsis. */
+export function ellipsize(value: string, width: number): string {
+	const chars = Array.from(value).map(sanitizeChar);
+	if (width <= 0) return "";
+	if (chars.length <= width) return chars.join("");
+	return `${chars.slice(0, Math.max(0, width - 1)).join("")}…`;
+}
+
+function renderRow(row: Cell[], theme: VizTheme): string {
+	let out = "";
+	let i = 0;
+	while (i < row.length) {
+		const start = row[i]!;
+		let text = "";
+		while (
+			i < row.length &&
+			row[i]!.color === start.color &&
+			!!row[i]!.bold === !!start.bold &&
+			!!row[i]!.inverse === !!start.inverse
+		) {
+			text += row[i]!.ch;
+			i++;
+		}
+		let styled = start.color && text.trim().length > 0 ? theme.fg(start.color, text) : text;
+		if (start.bold && theme.bold) styled = theme.bold(styled);
+		if (start.inverse && theme.inverse) styled = theme.inverse(styled);
+		out += styled;
+	}
+	return out;
+}

package/src/tui/viz/layout.ts

@@ -0,0 +1,111 @@
+/** Layout selection and panel rectangles for the /legion full view. */
+
+export type LayoutKind = "wide" | "stacked" | "portrait";
+
+export interface Rect {
+	x: number;
+	y: number;
+	w: number;
+	h: number;
+}
+
+export interface LegionLayout {
+	kind: LayoutKind;
+	header: Rect;
+	galaxy: Rect;
+	chart: Rect;
+	log: Rect;
+	footer: Rect;
+}
+
+export const WIDE_MIN_COLS = 140;
+export const PORTRAIT_MAX_COLS = 80;
+/** Kept for compatibility; tallness is now decided by aspect ratio alone. */
+export const TALL_PORTRAIT_MAX_COLS = 100;
+/** Chart rows in portrait: enough to read, never a tall skinny bar. */
+export const PORTRAIT_CHART_MIN = 10;
+export const PORTRAIT_CHART_MAX = 18;
+/** Side-by-side layouts never stretch panels beyond this many rows. */
+export const STACKED_TOP_MAX = 24;
+export const WIDE_CHART_MAX = 24;
+
+/** Terminal cells are ~2:1 (tall), so rows*2 >= cols means the window looks taller than wide. */
+export function isTall(cols: number, rows: number): boolean {
+	return rows * 2 >= cols;
+}
+
+export function selectLayout(cols: number, rows: number): LayoutKind {
+	if (cols < PORTRAIT_MAX_COLS) return "portrait";
+	if (isTall(cols, rows)) return "portrait";
+	if (cols >= WIDE_MIN_COLS) return "wide";
+	return "stacked";
+}
+
+export interface LayoutHints {
+	/** Number of log events, so a short history does not get a huge empty box. */
+	logEvents?: number;
+}
+
+export function computeLayout(cols: number, rows: number, hints: LayoutHints = {}): LegionLayout {
+	const W = Math.max(1, Math.floor(cols));
+	const H = Math.max(6, Math.floor(rows));
+	const kind = selectLayout(W, H);
+	const headerH = kind === "portrait" ? 2 : 1;
+	const header = { x: 0, y: 0, w: W, h: headerH };
+	const footer = { x: 0, y: H - 1, w: W, h: 1 };
+	const bodyY = headerH;
+	const bodyH = H - headerH - 1;
+	if (kind === "wide") {
+		const leftW = Math.floor(W * 0.6);
+		// Chart is capped; on very tall wide terminals the galaxy absorbs the rest.
+		const chartH = Math.min(WIDE_CHART_MAX, Math.max(3, Math.round(bodyH * 0.45)));
+		const galaxyH = bodyH - chartH;
+		return {
+			kind,
+			header,
+			footer,
+			galaxy: { x: 0, y: bodyY, w: leftW, h: galaxyH },
+			chart: { x: 0, y: bodyY + galaxyH, w: leftW, h: chartH },
+			log: { x: leftW, y: bodyY, w: W - leftW, h: bodyH },
+		};
+	}
+	if (kind === "stacked") {
+		const topH = Math.min(STACKED_TOP_MAX, Math.max(3, Math.round(bodyH * 0.58)));
+		const galaxyW = Math.floor(W * 0.5);
+		return {
+			kind,
+			header,
+			footer,
+			galaxy: { x: 0, y: bodyY, w: galaxyW, h: topH },
+			chart: { x: galaxyW, y: bodyY, w: W - galaxyW, h: topH },
+			log: { x: 0, y: bodyY + topH, w: W, h: bodyH - topH },
+		};
+	}
+	// Portrait: galaxy (aspect-limited), chart (fixed band), log gets the rest.
+	const chartH = Math.min(PORTRAIT_CHART_MAX, Math.max(PORTRAIT_CHART_MIN, Math.round(bodyH * 0.3)), Math.max(3, bodyH - 9));
+	// A visually round galaxy is ~W/2 rows tall (cells are 2:1); allow it up to ~W*0.6.
+	const galaxyCap = Math.max(8, Math.round(W * 0.5));
+	const galaxyGrowCap = Math.max(galaxyCap, Math.round(W * 0.65));
+	let galaxyH = Math.max(3, Math.min(galaxyCap, Math.round(bodyH * 0.4), bodyH - chartH - 6));
+	let logH = bodyH - galaxyH - chartH;
+	// Few events: give some of the empty log area back to the galaxy.
+	if (hints.logEvents !== undefined) {
+		const logNeeded = Math.max(8, hints.logEvents + 4);
+		const spare = logH - logNeeded;
+		if (spare > 0) {
+			const grow = Math.min(spare, galaxyGrowCap - galaxyH);
+			if (grow > 0) {
+				galaxyH += grow;
+				logH -= grow;
+			}
+		}
+	}
+	return {
+		kind,
+		header,
+		footer,
+		galaxy: { x: 0, y: bodyY, w: W, h: galaxyH },
+		chart: { x: 0, y: bodyY + galaxyH, w: W, h: chartH },
+		log: { x: 0, y: bodyY + galaxyH + chartH, w: W, h: Math.max(0, logH) },
+	};
+}

package/src/tui/viz/model.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared data model for the Legion visualization (railway strip + /legion view).
+ *
+ * Subagents spawn dynamically and nest, so nothing here assumes a fixed role
+ * list. Node statuses collapse to four display states: `blocked` is a
+ * transient in-memory approval flag and renders as running.
+ */
+
+import type { StatusEntry } from "../status.ts";
+
+export type VizStatus = "running" | "settled" | "failed" | "retired";
+
+export interface VizNode {
+	id: string;
+	name: string;
+	role: string;
+	parentId: string | null;
+	depth: number;
+	status: VizStatus;
+	startedAt: number;
+	/** Set once the node reaches a terminal display state. */
+	endedAt?: number;
+	/** Cumulative tokens reported for the node (input+cache+output; display totals). */
+	tokens: number;
+	/** Cumulative output tokens only; sampled for tok/s. */
+	tokensOut: number;
+	/**
+	 * Cumulative model-generation wall ms (assistant − prior user/toolResult).
+	 * Denominator for tok/s when > 0.
+	 */
+	generationMs: number;
+	/** Unix ms start of the current turn, when the status entry recorded one. */
+	currentTurnStartedAt?: number;
+	/** Unix ms the current turn settled. Absent while it is still in flight. */
+	currentTurnEndedAt?: number;
+}
+
+/** Same set the footer/busy label treat as active, so live counts agree everywhere. */
+const RUNNING = new Set(["starting", "working", "running", "blocked"]);
+const SETTLED = new Set(["settled", "success", "completed", "done"]);
+const FAILED = new Set(["failed", "aborted", "error", "truncated"]);
+
+export function displayStatus(state: string | undefined): VizStatus {
+	const value = (state ?? "").toLowerCase();
+	if (SETTLED.has(value)) return "settled";
+	if (FAILED.has(value)) return "failed";
+	if (RUNNING.has(value)) return "running";
+	return "retired";
+}
+
+/** Build viz nodes from status entries (root row included when present). */
+export function nodesFromEntries(entries: readonly StatusEntry[]): VizNode[] {
+	const out: VizNode[] = [];
+	const seen = new Set<string>();
+	for (const entry of entries) {
+		const id = entry.nodeId ?? entry.name;
+		if (seen.has(id)) continue;
+		seen.add(id);
+		const status = id === "root" ? "running" : displayStatus(entry.herdrStatus ?? entry.state);
+		out.push({
+			id,
+			name: entry.name,
+			role: entry.agent || "agent",
+			parentId: entry.parentId ?? (id === "root" ? null : entry.nodeId ? "root" : null),
+			depth: entry.depth ?? (id === "root" ? 0 : 1),
+			status,
+			startedAt: entry.startedAt,
+			...(status !== "running" ? { endedAt: entry.finishedAt ?? entry.startedAt } : {}),
+			tokens: Math.max(0, entry.tokensTotal ?? 0),
+			tokensOut: Math.max(0, entry.tokensOut ?? 0),
+			generationMs: Math.max(0, entry.generationMs ?? 0),
+			...(entry.currentTurnStartedAt !== undefined ? { currentTurnStartedAt: entry.currentTurnStartedAt } : {}),
+			...(entry.currentTurnEndedAt !== undefined ? { currentTurnEndedAt: entry.currentTurnEndedAt } : {}),
+		});
+	}
+	// Parents that are missing from the snapshot re-attach to the nearest known ancestor.
+	const ids = new Set(out.map((node) => node.id));
+	for (const node of out) {
+		if (node.parentId !== null && !ids.has(node.parentId)) node.parentId = ids.has("root") && node.id !== "root" ? "root" : null;
+	}
+	disambiguateNames(out);
+	return out;
+}
+
+/**
+ * Child supervisors number their own children, so a nested "scout-0" can share
+ * a name with a root-level "scout-0". Prefix duplicates with their parent name
+ * (the shallowest keeps the bare name) so strip/log/galaxy labels stay unique.
+ */
+export function disambiguateNames(nodes: VizNode[]): void {
+	const byName = new Map<string, VizNode[]>();
+	for (const node of nodes) byName.set(node.name, [...(byName.get(node.name) ?? []), node]);
+	const byId = new Map(nodes.map((node) => [node.id, node]));
+	for (const group of byName.values()) {
+		if (group.length < 2) continue;
+		const sorted = [...group].sort((a, b) => a.depth - b.depth || a.startedAt - b.startedAt);
+		for (const node of sorted.slice(1)) {
+			const parent = node.parentId ? byId.get(node.parentId) : undefined;
+			if (parent && parent.id !== "root") node.name = `${parent.name}/${node.name}`;
+		}
+	}
+}
+
+export function isAgent(node: VizNode): boolean {
+	return node.id !== "root" && node.parentId !== null;
+}
+
+export function formatCount(value: number): string {
+	if (!Number.isFinite(value) || value <= 0) return "0";
+	if (value < 1000) return String(Math.round(value));
+	if (value < 1_000_000) return `${(value / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+	return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+export function formatDuration(ms: number): string {
+	const total = Math.max(0, Math.floor(ms / 1000));
+	const h = Math.floor(total / 3600);
+	const m = Math.floor((total % 3600) / 60);
+	const s = total % 60;
+	if (h > 0) return `${h}h${String(m).padStart(2, "0")}m`;
+	if (m > 0) return `${m}m${String(s).padStart(2, "0")}s`;
+	return `${s}s`;
+}

package/src/tui/viz/palette.ts

@@ -0,0 +1,188 @@
+/**
+ * Role → pi theme token mapping. Colors are always theme tokens (never hex),
+ * so the visualization follows `/theme` changes automatically.
+ */
+
+import type { VizNode, VizStatus } from "./model.ts";
+
+export interface VizTheme {
+	fg(color: string, text: string): string;
+	bg?(color: string, text: string): string;
+	bold?(text: string): string;
+	inverse?(text: string): string;
+	getFgAnsi?(color: string): string;
+}
+
+export const ROLE_TOKENS: Readonly<Record<string, string>> = {
+	centurion: "accent",
+	planner: "syntaxKeyword",
+	worker: "syntaxVariable",
+	scout: "syntaxNumber",
+	reviewer: "syntaxFunction",
+	advisor: "syntaxString",
+};
+
+/** Fallback pool for roles that are not in the table (deterministic hash pick). */
+export const FALLBACK_TOKENS = [
+	"syntaxType",
+	"syntaxString",
+	"syntaxFunction",
+	"syntaxNumber",
+	"syntaxKeyword",
+	"syntaxVariable",
+	"syntaxOperator",
+] as const;
+
+function hash(value: string): number {
+	let h = 2166136261;
+	for (let i = 0; i < value.length; i++) {
+		h ^= value.charCodeAt(i);
+		h = Math.imul(h, 16777619);
+	}
+	return h >>> 0;
+}
+
+export function roleToken(role: string): string {
+	const key = role.toLowerCase();
+	return ROLE_TOKENS[key] ?? FALLBACK_TOKENS[hash(key) % FALLBACK_TOKENS.length]!;
+}
+
+/** Prefix marking a cell color as "the color of this agent type", resolved per theme at paint time. */
+export const ROLE_COLOR_PREFIX = "role:";
+
+/** Deferred per-type color; resolved by `resolveRolePalette` when a canvas is painted. */
+export function roleColor(role: string): string {
+	// The ledger root is the user's own pi session, not an agent type: keep it
+	// neutral so it never takes a type's color (centurion owns accent).
+	if (role.toLowerCase() === "root") return "text";
+	return `${ROLE_COLOR_PREFIX}${role.toLowerCase()}`;
+}
+
+/**
+ * Extra theme tokens tried, in order, when a type's preferred token renders
+ * with the same ANSI color as a type already assigned. pi's `system` theme in
+ * its palette-index tier (terminal reported no palette) maps accent AND
+ * syntaxNumber to ANSI slot 5, so centurion and scout were both magenta.
+ */
+export const DISTINCT_FALLBACK_TOKENS = [
+	"syntaxKeyword",
+	"syntaxVariable",
+	"syntaxNumber",
+	"syntaxFunction",
+	"syntaxString",
+	"syntaxType",
+	"success",
+	"warning",
+	"accent",
+	"mdLink",
+	"mdHeading",
+	"mdCode",
+	"thinkingHigh",
+	"thinkingMedium",
+	"toolDiffAdded",
+	"bashMode",
+] as const;
+
+/** ANSI prefix a token renders with. */
+export function tokenAnsi(theme: VizTheme, token: string): string {
+	try {
+		if (typeof theme.getFgAnsi === "function") return theme.getFgAnsi(token);
+		return theme.fg(token, "\u0000").split("\u0000")[0] ?? token;
+	} catch {
+		return `?${token}`;
+	}
+}
+
+type Swatch = { kind: "rgb"; l: number; a: number; b: number } | { kind: "key"; key: string };
+
+function xterm256(n: number): [number, number, number] {
+	if (n >= 232) {
+		const v = 8 + 10 * (n - 232);
+		return [v, v, v];
+	}
+	const i = n - 16;
+	const step = [0, 95, 135, 175, 215, 255];
+	return [step[Math.floor(i / 36)]!, step[Math.floor(i / 6) % 6]!, step[i % 6]!];
+}
+
+function oklab(r: number, g: number, b: number): Swatch {
+	const lin = (c: number) => {
+		const v = c / 255;
+		return v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
+	};
+	const [R, G, B] = [lin(r), lin(g), lin(b)];
+	const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+	const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
+	const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
+	return {
+		kind: "rgb",
+		l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+		a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+		b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+	};
+}
+
+/**
+ * What a token actually looks like: an OKLab color for truecolor / 256-color
+ * output, or an opaque key for the 16 terminal-defined palette slots (whose
+ * real color is unknown, so only the same slot counts as equal).
+ */
+export function tokenSwatch(theme: VizTheme, token: string): Swatch {
+	const ansi = tokenAnsi(theme, token);
+	const rgb = /38;2;(\d+);(\d+);(\d+)/.exec(ansi);
+	if (rgb) return oklab(Number(rgb[1]), Number(rgb[2]), Number(rgb[3]));
+	const idx = /38;5;(\d+)/.exec(ansi);
+	if (idx && Number(idx[1]) >= 16) return oklab(...xterm256(Number(idx[1])));
+	const basic = /(?:^|\[|;)(3[0-7]|9[0-7])m/.exec(ansi);
+	return { kind: "key", key: idx ? `p${idx[1]}` : basic ? `b${basic[1]}` : ansi };
+}
+
+/** OKLab distance below which two colors read as the same (~JND); pi's own dark/light role tokens are >= 0.04 apart, the system-theme accent/syntaxNumber clash is ~0.002. */
+export const MIN_TYPE_COLOR_DISTANCE = 0.025;
+
+export function swatchesClash(x: Swatch, y: Swatch): boolean {
+	if (x.kind === "key" || y.kind === "key") return x.kind === y.kind && (x as { key: string }).key === (y as { key: string }).key;
+	return Math.hypot(x.l - y.l, x.a - y.a, x.b - y.b) < MIN_TYPE_COLOR_DISTANCE;
+}
+
+const ROLE_ORDER = Object.keys(ROLE_TOKENS);
+
+/**
+ * Map each agent type present to a theme token so that, where the theme can
+ * tell them apart, no two types share an on-screen color (nor the failed /
+ * retired colors). Known types are assigned first in table order so their
+ * preferred tokens win; the rest follow alphabetically (deterministic).
+ */
+export function resolveRolePalette(theme: VizTheme, roles: Iterable<string>): Map<string, string> {
+	const unique = [...new Set([...roles].map((role) => role.toLowerCase()))].sort((a, b) => {
+		const ia = ROLE_ORDER.indexOf(a);
+		const ib = ROLE_ORDER.indexOf(b);
+		return (ia < 0 ? 99 : ia) - (ib < 0 ? 99 : ib) || a.localeCompare(b);
+	});
+	// Compare what the colors LOOK like, not their escape bytes: pi's system
+	// theme derives accent and syntaxNumber from the same palette slot, giving
+	// e.g. #b38eb9 vs #b38fb8 in truecolor — different bytes, same pink.
+	const used: Swatch[] = [tokenSwatch(theme, "error"), tokenSwatch(theme, "dim")];
+	const out = new Map<string, string>();
+	for (const role of unique) {
+		const preferred = roleToken(role);
+		const candidates = [preferred, ...FALLBACK_TOKENS.slice(hash(role) % FALLBACK_TOKENS.length), ...DISTINCT_FALLBACK_TOKENS];
+		const pick = candidates.find((token) => {
+			const swatch = tokenSwatch(theme, token);
+			return !used.some((other) => swatchesClash(swatch, other));
+		}) ?? preferred;
+		used.push(tokenSwatch(theme, pick));
+		out.set(role, pick);
+	}
+	return out;
+}
+
+export function statusToken(role: string, status: VizStatus): string {
+	if (status === "failed") return "error";
+	if (status === "retired") return "dim";
+	return roleColor(role);
+}
+
+export function nodeToken(node: Pick<VizNode, "role" | "status">): string {
+	return statusToken(node.role, node.status);
+}