@adeildo/pi-look 4.0.0

package/src/data/totals.ts

@@ -0,0 +1,149 @@
+// What a session spent and how fast it went, added up from its own entries. Pi keeps the same totals
+// for its footer but does not export the helper, so this is the one place that sums them.
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export interface Totals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+}
+
+interface UsageLike {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: { total: number };
+}
+
+/**
+ * What one request to the model left behind. Pi records usage without a duration, so this entry is
+ * where the session speeds come from after a resume.
+ */
+export interface RequestRecord {
+	/** Tokens the model wrote. */
+	output: number;
+	/** Tokens sent: fresh input plus what was read from and written to the cache. */
+	prompt: number;
+	/** From the request leaving to the first piece of the answer. */
+	firstTokenMs: number;
+	/** From the first piece of the answer to the last. */
+	generationMs: number;
+}
+
+export const REQUEST_ENTRY = "pi-look:request";
+/** Written by this package before it was renamed. It has no `prompt`, so it only counts for decode. */
+const LEGACY_ENTRY = "pi-statusline:turn";
+
+export interface Averages {
+	/** Output tokens per second of writing, across the branch. */
+	decode: number | undefined;
+	/** Prompt tokens per second of waiting for the first token, across the branch. */
+	prefill: number | undefined;
+}
+
+export function emptyTotals(): Totals {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+
+export function promptOf(totals: Totals): number {
+	return totals.input + totals.cacheRead + totals.cacheWrite;
+}
+
+export function tokensOf(totals: Totals): number {
+	return promptOf(totals) + totals.output;
+}
+
+export function usageTotals(usage: UsageLike): Totals {
+	const totals = emptyTotals();
+	add(totals, usage);
+	return totals;
+}
+
+/** The whole branch, not just the messages after the last compaction. */
+export function totalsOf(entries: readonly SessionEntry[]): Totals {
+	const totals = emptyTotals();
+
+	for (const entry of entries) {
+		if (entry.type === "usage") add(totals, entry.usage);
+		else if (entry.type === "message" && entry.message.role === "assistant")
+			add(totals, entry.message.usage);
+		else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage)
+			add(totals, entry.message.usage);
+		else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage)
+			add(totals, entry.usage);
+	}
+
+	return totals;
+}
+
+/** How much of the last prompt came from the cache, the way pi's own footer reports it. */
+export function cacheHitPercent(entries: readonly SessionEntry[]): number | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
+
+		const usage = entry.message.usage;
+		const prompt = usage.input + usage.cacheRead + usage.cacheWrite;
+		return prompt === 0 ? undefined : (usage.cacheRead / prompt) * 100;
+	}
+	return undefined;
+}
+
+export function cacheWarming(entries: readonly SessionEntry[]): boolean {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry?.type !== "message" || entry.message.role !== "assistant") continue;
+		return entry.message.usage.cacheRead === 0 && entry.message.usage.cacheWrite > 0;
+	}
+	return false;
+}
+
+export function averagesOf(entries: readonly SessionEntry[]): Averages {
+	let output = 0;
+	let generationMs = 0;
+	let prompt = 0;
+	let waitingMs = 0;
+
+	for (const entry of entries) {
+		if (entry.type !== "custom") continue;
+		if (entry.customType !== REQUEST_ENTRY && entry.customType !== LEGACY_ENTRY) continue;
+		const record = entry.data;
+		if (!isRecord(record)) continue;
+
+		output += record.output;
+		generationMs += record.generationMs;
+		if (typeof record.prompt === "number" && record.prompt > 0) {
+			prompt += record.prompt;
+			waitingMs += record.firstTokenMs;
+		}
+	}
+
+	return { decode: perSecond(output, generationMs), prefill: perSecond(prompt, waitingMs) };
+}
+
+export function perSecond(tokens: number, milliseconds: number): number | undefined {
+	return tokens > 0 && milliseconds > 0 ? tokens / (milliseconds / 1000) : undefined;
+}
+
+function isRecord(
+	data: unknown,
+): data is Omit<RequestRecord, "prompt"> & { prompt?: number | undefined } {
+	if (typeof data !== "object" || data === null) return false;
+	const record = data as Partial<RequestRecord>;
+	return (
+		typeof record.output === "number" &&
+		typeof record.firstTokenMs === "number" &&
+		typeof record.generationMs === "number"
+	);
+}
+
+function add(totals: Totals, usage: UsageLike): void {
+	totals.input += usage.input;
+	totals.output += usage.output;
+	totals.cacheRead += usage.cacheRead;
+	totals.cacheWrite += usage.cacheWrite;
+	totals.cost += usage.cost.total;
+}

package/src/desktop/palette.ts

@@ -0,0 +1,207 @@
+// The desktop palette as a pi theme. DankMaterialShell runs matugen over the wallpaper and keeps the
+// result in one file: the Material roles for dark and light, and sixteen terminal colours. Pi wants
+// 51 tokens. This maps one onto the other, so the terminal, the shell and pi share one palette.
+//
+// Every value comes from the file. Where Material has no role, like success or a diff line, the
+// terminal colour of that hue stands in, and tinted backgrounds are a surface mixed with that hue.
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+export const DESKTOP_THEME = "desktop";
+
+export type Mode = "dark" | "light";
+
+/** The parts of `dms-colors.json` the theme reads. */
+export interface DesktopColors {
+	mode: Mode;
+	/** Material roles, like `primary` and `surface_container_high`. */
+	roles: Readonly<Record<string, string>>;
+	/** The sixteen terminal colours, `color0` to `color15`, for this mode. */
+	terminal: Readonly<Record<string, string>>;
+}
+
+export interface ThemeJson {
+	$schema: string;
+	name: string;
+	vars: Record<string, string>;
+	colors: Record<string, string>;
+	export: { pageBg: string; cardBg: string; infoBg: string };
+}
+
+const HEX = /^#[0-9a-f]{6}$/i;
+
+/** Reads the file's JSON. Undefined when it is not the shape DankMaterialShell writes. */
+export function parseDesktopColors(json: unknown, mode?: Mode): DesktopColors | undefined {
+	if (!isRecord(json) || !isRecord(json.colors) || !isRecord(json.dank16)) return undefined;
+	const chosen: Mode = mode ?? (json.mode === "light" ? "light" : "dark");
+	const roles = json.colors[chosen];
+	if (!isRecord(roles)) return undefined;
+
+	const terminal: Record<string, string> = {};
+	for (const [name, value] of Object.entries(json.dank16)) {
+		const hex = isRecord(value) ? (value[chosen] ?? value.default) : value;
+		if (typeof hex === "string" && HEX.test(hex)) terminal[name] = hex;
+	}
+
+	const material: Record<string, string> = {};
+	for (const [name, value] of Object.entries(roles)) {
+		if (typeof value === "string" && HEX.test(value)) material[name] = value;
+	}
+	return { mode: chosen, roles: material, terminal };
+}
+
+/** The roles and colours the mapping needs. A file missing any of them does not become a theme. */
+const REQUIRED_ROLES = [
+	"primary",
+	"secondary",
+	"tertiary",
+	"error",
+	"error_container",
+	"outline",
+	"outline_variant",
+	"on_surface",
+	"on_surface_variant",
+	"surface",
+	"surface_container_low",
+	"surface_container",
+	"surface_container_high",
+	"surface_container_highest",
+];
+const REQUIRED_TERMINAL = ["color1", "color2", "color3", "color6", "color9"];
+
+export function missingColors(colors: DesktopColors): string[] {
+	return [
+		...REQUIRED_ROLES.filter((role) => colors.roles[role] === undefined),
+		...REQUIRED_TERMINAL.filter((name) => colors.terminal[name] === undefined),
+	];
+}
+
+export function desktopTheme(colors: DesktopColors): ThemeJson {
+	const role = (name: string): string => colors.roles[name] ?? "#808080";
+	const term = (name: string): string => colors.terminal[name] ?? "#808080";
+
+	const vars: Record<string, string> = {
+		primary: role("primary"),
+		secondary: role("secondary"),
+		tertiary: role("tertiary"),
+		error: role("error"),
+		outline: role("outline"),
+		outlineVariant: role("outline_variant"),
+		text: role("on_surface"),
+		subtext: role("on_surface_variant"),
+		surface: role("surface"),
+		containerLow: role("surface_container_low"),
+		container: role("surface_container"),
+		containerHigh: role("surface_container_high"),
+		containerHighest: role("surface_container_highest"),
+		red: term("color1"),
+		green: term("color2"),
+		yellow: term("color3"),
+		cyan: term("color6"),
+		brightRed: term("color9"),
+		successBg: mix(role("surface_container_low"), term("color2"), 0.12),
+		errorBg: mix(role("surface_container_low"), role("error"), 0.14),
+		infoBg: mix(role("surface_container"), term("color3"), 0.1),
+	};
+
+	const colorsByToken: Record<ThemeColor | BackgroundToken, string> = {
+		accent: "primary",
+		border: "outline",
+		borderAccent: "primary",
+		borderMuted: "outlineVariant",
+		success: "green",
+		error: "error",
+		warning: "yellow",
+		muted: "subtext",
+		dim: "outline",
+		text: "text",
+		thinkingText: "subtext",
+
+		selectedBg: "containerHigh",
+		scrollbarTrack: "outlineVariant",
+		scrollbarThumb: "subtext",
+		searchMatchBg: "containerHighest",
+		searchMatchText: "text",
+		userMessageBg: "container",
+		userMessageText: "text",
+		customMessageBg: "containerLow",
+		customMessageText: "text",
+		customMessageLabel: "tertiary",
+		toolPendingBg: "containerLow",
+		toolSuccessBg: "successBg",
+		toolErrorBg: "errorBg",
+		toolTitle: "text",
+		toolOutput: "subtext",
+
+		mdHeading: "tertiary",
+		mdLink: "primary",
+		mdLinkUrl: "outline",
+		mdCode: "secondary",
+		mdCodeBlock: "text",
+		mdCodeBlockBorder: "outlineVariant",
+		mdQuote: "subtext",
+		mdQuoteBorder: "outlineVariant",
+		mdHr: "outlineVariant",
+		mdListBullet: "primary",
+
+		toolDiffAdded: "green",
+		toolDiffRemoved: "red",
+		toolDiffContext: "subtext",
+
+		syntaxComment: "outline",
+		syntaxKeyword: "primary",
+		syntaxFunction: "tertiary",
+		syntaxVariable: "text",
+		syntaxString: "green",
+		syntaxNumber: "yellow",
+		syntaxType: "cyan",
+		syntaxOperator: "subtext",
+		syntaxPunctuation: "subtext",
+
+		// The effort ramp runs from the quiet outline through the palette's own hues to the terminal
+		// reds, which keep their meaning whatever the wallpaper, so the frame warms up with the effort.
+		thinkingOff: "outlineVariant",
+		thinkingMinimal: "outline",
+		thinkingLow: "secondary",
+		thinkingMedium: "primary",
+		thinkingHigh: "tertiary",
+		thinkingXhigh: "brightRed",
+		thinkingMax: "red",
+
+		bashMode: "green",
+	};
+
+	return {
+		$schema:
+			"https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
+		name: DESKTOP_THEME,
+		vars,
+		colors: colorsByToken,
+		export: { pageBg: vars.surface ?? "", cardBg: vars.container ?? "", infoBg: vars.infoBg ?? "" },
+	};
+}
+
+type BackgroundToken =
+	| "selectedBg"
+	| "searchMatchBg"
+	| "userMessageBg"
+	| "customMessageBg"
+	| "toolPendingBg"
+	| "toolSuccessBg"
+	| "toolErrorBg";
+
+/** `base` moved `amount` of the way towards `tint`, in sRGB, which is enough for a faint wash. */
+export function mix(base: string, tint: string, amount: number): string {
+	const a = channels(base);
+	const b = channels(tint);
+	const mixed = a.map((value, index) => Math.round(value + ((b[index] ?? value) - value) * amount));
+	return `#${mixed.map((value) => value.toString(16).padStart(2, "0")).join("")}`;
+}
+
+function channels(hex: string): number[] {
+	const value = HEX.test(hex) ? hex.slice(1) : "808080";
+	return [0, 2, 4].map((offset) => Number.parseInt(value.slice(offset, offset + 2), 16));
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/desktop/sync.ts

@@ -0,0 +1,86 @@
+// Keeps `~/.pi/agent/themes/desktop.json` equal to the desktop palette. Pi reloads the active theme
+// from that folder by itself, so changing the wallpaper recolours a running pi with no restart.
+import { type FSWatcher, watch } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { DESKTOP_THEME, desktopTheme, missingColors, parseDesktopColors } from "./palette.ts";
+
+/** matugen writes a few files in a burst; one rewrite per burst is enough. */
+const SETTLE_MS = 250;
+
+export type SyncResult =
+	| { kind: "written"; path: string }
+	| { kind: "unchanged"; path: string }
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string };
+
+export function themePath(): string {
+	return join(getAgentDir(), "themes", `${DESKTOP_THEME}.json`);
+}
+
+export function expandHome(path: string): string {
+	return path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(1)) : path;
+}
+
+/** Writes the theme when the palette differs from what is on disk. */
+export async function syncDesktopTheme(source: string): Promise<SyncResult> {
+	let raw: string;
+	try {
+		raw = await readFile(expandHome(source), "utf8");
+	} catch {
+		return { kind: "missing" };
+	}
+
+	let json: unknown;
+	try {
+		json = JSON.parse(raw);
+	} catch {
+		return { kind: "invalid", reason: "the palette file is not JSON" };
+	}
+
+	const colors = parseDesktopColors(json);
+	if (colors === undefined) return { kind: "invalid", reason: "not a DankMaterialShell palette" };
+	const missing = missingColors(colors);
+	if (missing.length > 0) return { kind: "invalid", reason: `missing ${missing.join(", ")}` };
+
+	const path = themePath();
+	const next = `${JSON.stringify(desktopTheme(colors), null, "\t")}\n`;
+	const current = await readFile(path, "utf8").catch(() => undefined);
+	if (current === next) return { kind: "unchanged", path };
+
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, next);
+	return { kind: "written", path };
+}
+
+/**
+ * Watches the folder rather than the file: tools that write atomically replace the file, and a
+ * watch on the old one goes quiet.
+ */
+export function watchDesktopPalette(source: string, changed: () => void): () => void {
+	const path = expandHome(source);
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let watcher: FSWatcher | undefined;
+
+	try {
+		watcher = watch(dirname(path), (_event, file) => {
+			if (file !== null && file !== basename(path)) return;
+			if (timer !== undefined) clearTimeout(timer);
+			timer = setTimeout(changed, SETTLE_MS);
+			timer.unref?.();
+		});
+		watcher.unref?.();
+		watcher.on("error", () => watcher?.close());
+	} catch {
+		return () => {};
+	}
+
+	return () => {
+		if (timer !== undefined) clearTimeout(timer);
+		watcher?.close();
+	};
+}