@adeildo/pi-harness 4.0.0

package/src/look/data/telemetry.ts

@@ -0,0 +1,188 @@
+// The clock behind the speeds. A run is everything between the prompt and the agent settling; a
+// request is one call to the model inside it. Both are measured from the message events, because pi
+// records usage without a duration.
+//
+// Two speeds per request, one for each direction:
+//   ↑ prefill: prompt tokens over the wait for the first token, how fast what we sent was taken in
+//   ↓ decode:  output tokens over the time spent writing, how fast the answer comes back
+import {
+	emptyTotals,
+	perSecond,
+	promptOf,
+	type RequestRecord,
+	type Totals,
+	usageTotals,
+} from "./totals.ts";
+
+/** A decode speed over less than this is noise, so it waits. */
+const MIN_SAMPLE_MS = 250;
+/** Close enough for a live number: the provider's real count replaces it at the end. */
+const CHARS_PER_TOKEN = 4;
+
+export interface RequestView {
+	/** The answer is still arriving. */
+	streaming: boolean;
+	/** Waiting for the first token right now. */
+	waiting: boolean;
+	/** Since the request left, frozen when it ends. */
+	elapsedMs: number;
+	firstTokenMs: number | undefined;
+	/** Output tokens per second, live while streaming. */
+	decode: number | undefined;
+	/** Prompt tokens per second of waiting, once the prompt size is known. */
+	prefill: number | undefined;
+	/** What this request used so far. */
+	usage: Totals;
+	/** The output count is an estimate until the provider reports it. */
+	estimated: boolean;
+}
+
+export interface RunView {
+	running: boolean;
+	elapsedMs: number;
+	/** Requests made in this run. */
+	requests: number;
+}
+
+interface Request {
+	startedAt: number;
+	firstTokenAt: number | undefined;
+	endedAt: number | undefined;
+	usage: Totals;
+	/** Characters seen, for a live rate before the provider says how many tokens they were. */
+	characters: number;
+}
+
+interface Run {
+	startedAt: number;
+	endedAt: number | undefined;
+	requests: number;
+}
+
+interface UsageLike {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: { total: number };
+}
+
+export class Telemetry {
+	readonly #now: () => number;
+	#run: Run | undefined;
+	#request: Request | undefined;
+	/** The last request that finished, frozen, so a line can show numbers that no longer move. */
+	#last: RequestView | undefined;
+
+	constructor(now: () => number = Date.now) {
+		this.#now = now;
+	}
+
+	runStarted(): void {
+		this.#run = { startedAt: this.#now(), endedAt: undefined, requests: 0 };
+	}
+
+	runEnded(): void {
+		if (this.#run !== undefined && this.#run.endedAt === undefined) this.#run.endedAt = this.#now();
+	}
+
+	/** A turn starting is the request leaving. */
+	requestStarted(): void {
+		this.#request = {
+			startedAt: this.#now(),
+			firstTokenAt: undefined,
+			endedAt: undefined,
+			usage: emptyTotals(),
+			characters: 0,
+		};
+		if (this.#run === undefined || this.#run.endedAt !== undefined) this.runStarted();
+		if (this.#run !== undefined) this.#run.requests++;
+	}
+
+	/** The assistant message opening. Starts a request when no turn announced one. */
+	answerStarted(): void {
+		if (this.#request === undefined || this.#request.endedAt !== undefined) this.requestStarted();
+	}
+
+	/** A piece of the answer: text, thinking or a tool call being written. */
+	answerGrew(delta: string, usage: UsageLike): void {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return;
+		request.usage = usageTotals(usage);
+		if (delta.length === 0) return;
+		request.characters += delta.length;
+		request.firstTokenAt ??= this.#now();
+	}
+
+	/** The answer is complete. Returns what the session keeps, or nothing when there was no answer. */
+	answerEnded(usage: UsageLike): RequestRecord | undefined {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return undefined;
+
+		const now = this.#now();
+		request.endedAt = now;
+		request.usage = usageTotals(usage);
+		if (request.usage.output === 0 && request.firstTokenAt === undefined) return undefined;
+
+		const firstTokenAt = request.firstTokenAt ?? now;
+		this.#last = this.request();
+		return {
+			output: request.usage.output,
+			prompt: promptOf(request.usage),
+			firstTokenMs: firstTokenAt - request.startedAt,
+			generationMs: now - firstTokenAt,
+		};
+	}
+
+	/** The request running now, or the last one. */
+	request(): RequestView | undefined {
+		const request = this.#request;
+		if (request === undefined) return undefined;
+
+		const now = this.#now();
+		const streaming = request.endedAt === undefined;
+		const firstTokenMs =
+			request.firstTokenAt === undefined ? undefined : request.firstTokenAt - request.startedAt;
+		const estimated = streaming && request.usage.output === 0;
+		const output = estimated
+			? Math.round(request.characters / CHARS_PER_TOKEN)
+			: request.usage.output;
+		const writingMs =
+			request.firstTokenAt === undefined ? 0 : (request.endedAt ?? now) - request.firstTokenAt;
+
+		return {
+			streaming,
+			waiting: streaming && request.firstTokenAt === undefined,
+			elapsedMs: (request.endedAt ?? now) - request.startedAt,
+			firstTokenMs,
+			decode: writingMs < MIN_SAMPLE_MS && streaming ? undefined : perSecond(output, writingMs),
+			prefill:
+				firstTokenMs === undefined ? undefined : perSecond(promptOf(request.usage), firstTokenMs),
+			usage: { ...request.usage, output },
+			estimated,
+		};
+	}
+
+	/** The last request that finished. Undefined until one has. */
+	last(): RequestView | undefined {
+		return this.#last;
+	}
+
+	/** The run going now, or the last one. */
+	run(): RunView | undefined {
+		const run = this.#run;
+		if (run === undefined) return undefined;
+		const running = run.endedAt === undefined;
+		return {
+			running,
+			elapsedMs: (run.endedAt ?? this.#now()) - run.startedAt,
+			requests: run.requests,
+		};
+	}
+
+	reset(): void {
+		this.#run = undefined;
+		this.#request = undefined;
+		this.#last = undefined;
+	}
+}

package/src/look/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/look/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/look/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();
+	};
+}