@adeildo/pi-look 4.1.0 → 5.0.0

package/src/index.ts

@@ -1,6 +1,3 @@
-// The look: pi's start screen, editor, footer and working line, redrawn around the data I want in
-// front of me, in the colours of whatever theme is on. One feature, because the pieces share one clock
-// and one git probe; each piece has its own switch in the settings.
 import { createApp, defineFeature, type FeatureScope } from "@adeildo/pi-kit";
 import type {
 	ExtensionAPI,
@@ -12,6 +9,7 @@ import type { TUI } from "@earendil-works/pi-tui";
 import { type GitState, readGit } from "./data/git.ts";
 import { emptySnapshot, type Snapshot, SnapshotReader } from "./data/snapshot.ts";
 import { Telemetry } from "./data/telemetry.ts";
+import type { DeltaKind } from "./data/telemetry.ts";
 import { REQUEST_ENTRY, type RequestRecord } from "./data/totals.ts";
 import { DESKTOP_THEME } from "./desktop/palette.ts";
 import { syncDesktopTheme, watchDesktopPalette } from "./desktop/sync.ts";
@@ -34,6 +32,7 @@ import {
 	pathLength,
 	peek,
 	separator,
+	SECTIONS,
 	SEPARATORS,
 	strip,
 	topLeft,
@@ -43,7 +42,7 @@ import { applyCursor, LookEditor } from "./ui/editor.ts";
 import { FooterComponent, StripComponent } from "./ui/footer.ts";
 import { HeaderComponent, type LoadedCounts } from "./ui/header.ts";
 import type { Screen, SlotName } from "./ui/screen.ts";
-import { type Activity, callingTool, describe, thinkingTail, toolDetail } from "./ui/working.ts";
+import { type Activity, describe, draftedTool } from "./ui/working.ts";
 
 export { SEGMENT_IDS, SEGMENTS, type SegmentId } from "./render/segments.ts";
 export { ROLE_TOKENS } from "./render/paint.ts";
@@ -51,8 +50,6 @@ export { desktopTheme, parseDesktopColors } from "./desktop/palette.ts";
 
 const STRIP_WIDGET = "pi-look:strip";
 const TICK_MS = 500;
-/** The thinking tail changes on every token; the spinner line does not need to. */
-const PEEK_MS = 120;
 
 interface Live {
 	ctx: ExtensionContext | undefined;
@@ -63,16 +60,15 @@ interface Live {
 	probing: boolean;
 	ticker: ReturnType<typeof setInterval> | undefined;
 	stopWatching: (() => void) | undefined;
-	/** The frame's snapshot, shared by every component drawn in the same frame. */
 	frame: Snapshot | undefined;
 	activity: string | undefined;
-	peekAt: number;
 }
 
 export const look = defineFeature({
 	id: "look",
 	description:
 		"The start screen, a framed editor, the footer and a working line that says what runs",
+	sections: SECTIONS,
 	settings: LOOK_SETTINGS,
 	setup(scope) {
 		const telemetry = new Telemetry();
@@ -88,7 +84,6 @@ export const look = defineFeature({
 			stopWatching: undefined,
 			frame: undefined,
 			activity: undefined,
-			peekAt: 0,
 		};
 
 		const screen = createScreen(scope, live, reader, telemetry);
@@ -144,6 +139,11 @@ export const look = defineFeature({
 			live.tui = undefined;
 		});
 
+		// These two fire for the calls the agent makes, and not for pi's cache warming, which calls the
+		// provider on its own: the marks always belong to the answer being measured.
+		scope.on("before_provider_request", () => telemetry.providerRequestSent());
+		scope.on("after_provider_response", () => telemetry.providerResponseArrived());
+
 		scope.on("agent_start", () => {
 			telemetry.runStarted();
 			setActivity(live, scope, { kind: "waiting" });
@@ -164,39 +164,31 @@ export const look = defineFeature({
 			if (message.role !== "assistant") return;
 			const update = event.assistantMessageEvent;
 			const delta = "delta" in update ? update.delta : "";
-			telemetry.answerGrew(delta, message.usage);
+			const kind: DeltaKind = update.type.startsWith("thinking") ? "thinking" : "writing";
+			telemetry.answerGrew(delta, message.usage, kind);
 
-			if (update.type === "thinking_delta") {
-				const now = Date.now();
-				if (now - live.peekAt < PEEK_MS) return;
-				live.peekAt = now;
-				setActivity(live, scope, { kind: "thinking", tail: thinkingTail(message.content) });
+			if (update.type === "thinking_start" || update.type === "thinking_delta") {
+				setActivity(live, scope, { kind: "thinking" });
 			} else if (update.type === "text_delta" || update.type === "text_start") {
 				setActivity(live, scope, { kind: "writing" });
 			} else if (update.type === "toolcall_start" || update.type === "toolcall_delta") {
-				const tool = callingTool(message.content);
-				if (tool !== undefined) setActivity(live, scope, { kind: "calling", tool });
+				const tool = draftedTool(message.content);
+				if (tool !== undefined) setActivity(live, scope, { kind: "drafting", tool });
 			}
 		});
 
 		scope.on("message_end", (event) => {
 			if (event.message.role !== "assistant") return;
 			const record = telemetry.answerEnded(event.message.usage);
-			// Kept in the session, so the average speeds survive a resume, and the usage ledger gets a
-			// duration, which pi does not record.
+			// Pi records usage without a duration, so the session keeps it for the speeds after a resume.
 			if (record !== undefined) scope.appendEntry<RequestRecord>(REQUEST_ENTRY, record);
 			repaint();
 		});
 
 		scope.on("tool_execution_start", (event) => {
-			setActivity(live, scope, {
-				kind: "running",
-				tool: event.toolName,
-				detail: toolDetail(event.args),
-			});
+			setActivity(live, scope, { kind: "running", tool: event.toolName });
 		});
 
-		// A command may have moved the branch or touched the tree.
 		scope.on("tool_execution_end", () => void probeGit(live));
 
 		scope.on("agent_end", () => {
@@ -213,41 +205,35 @@ export const look = defineFeature({
 		scope.on("session_compact", repaint);
 		scope.on("session_tree", repaint);
 
-		scope.registerCommand("look", {
-			description:
-				"Look: `explain` says what every piece on screen is, `theme` switches to the desktop theme",
-			getArgumentCompletions: (prefix) =>
-				["explain", "theme"]
-					.filter((name) => name.startsWith(prefix.trim()))
-					.map((name) => ({ value: name, label: name })),
-			handler: async (args, ctx) => {
-				const action = args.trim();
-				if (action === "" || action === "explain") {
-					ctx.ui.notify(explain(screen), "info");
-					return;
-				}
-				if (action !== "theme") {
-					ctx.ui.notify("usage: /look explain | /look theme", "info");
-					return;
-				}
-				const result = await syncDesktopTheme(desktopSource.get(scope));
-				if (result.kind === "missing" || result.kind === "invalid") {
-					const why = result.kind === "missing" ? "no palette file" : result.reason;
-					ctx.ui.notify(`look: cannot build the desktop theme: ${why}`, "warning");
-					return;
-				}
-				const switched = ctx.ui.setTheme(DESKTOP_THEME);
-				ctx.ui.notify(
-					switched.success
-						? `look: now on the ${DESKTOP_THEME} theme, from ${desktopSource.get(scope)}`
-						: `look: wrote ${result.path}, but pi did not load it: ${switched.error ?? "unknown"}`,
-					switched.success ? "info" : "warning",
-				);
-			},
+		scope.screen.action({
+			id: "explain",
+			section: "Slots",
+			label: "What is on screen",
+			description: "Every piece the slots show right now, and what it means.",
+			run: () => explain(screen),
+		});
+
+		scope.screen.action({
+			id: "desktop.apply",
+			section: "Desktop theme",
+			label: "Switch to it now",
+			description: "Builds the desktop theme from the palette file and makes it pi's theme.",
+			run: (ctx) => switchToDesktopTheme(ctx, scope),
 		});
 	},
 });
 
+async function switchToDesktopTheme(ctx: ExtensionContext, scope: FeatureScope): Promise<string> {
+	const source = desktopSource.get(scope);
+	const result = await syncDesktopTheme(source);
+	if (result.kind === "missing") throw new Error(`no palette at ${source}`);
+	if (result.kind === "invalid") throw new Error(`cannot build the theme: ${result.reason}`);
+	const switched = ctx.ui.setTheme(DESKTOP_THEME);
+	if (!switched.success)
+		throw new Error(`wrote ${result.path}, but pi did not load it: ${switched.error ?? "unknown"}`);
+	return `Now on the ${DESKTOP_THEME} theme, built from ${source}.`;
+}
+
 const SLOT_TITLES: Record<SlotName, string> = {
 	strip: "Above the editor, this answer",
 	topLeft: "Frame, top left",
@@ -257,7 +243,6 @@ const SLOT_TITLES: Record<SlotName, string> = {
 	below: "Below the editor, the session",
 };
 
-/** Every piece on screen, where it is, what it shows now and what it means. */
 function explain(screen: Screen): string {
 	const snapshot = screen.snapshot();
 	const paint = screen.paint();
@@ -309,7 +294,6 @@ function createScreen(
 		snapshot() {
 			const ctx = live.ctx;
 			if (ctx === undefined) return emptySnapshot();
-			// Every component of one frame renders in the same tick, so they share one read.
 			if (live.frame !== undefined) return live.frame;
 			const snapshot = reader.read(ctx, {
 				branch: live.footerData?.getGitBranch() ?? null,
@@ -373,7 +357,6 @@ function installHeader(ctx: ExtensionContext, screen: Screen, scope: FeatureScop
 	);
 }
 
-/** What loaded, from pi's own lists: active tools, skill and prompt commands, extension files. */
 function loadedCounts(pi: ExtensionAPI): LoadedCounts {
 	const commands = pi.getCommands();
 	const extensions = new Set<string>();
@@ -417,7 +400,6 @@ function setActivity(live: Live, scope: FeatureScope, activity: Activity): void
 	live.ctx?.ui.setWorkingMessage(message);
 }
 
-/** Only one at a time, and never while a render is waiting on it. */
 async function probeGit(live: Live): Promise<void> {
 	const ctx = live.ctx;
 	if (ctx === undefined || live.probing) return;
@@ -430,7 +412,6 @@ async function probeGit(live: Live): Promise<void> {
 	}
 }
 
-/** The clocks have to move on their own while the model thinks and nothing else happens. */
 function startTicking(live: Live): void {
 	stopTicking(live);
 	live.ticker = setInterval(() => live.repaint?.(), TICK_MS);

package/src/render/fit.ts

@@ -1,20 +1,13 @@
-// Making pieces fit. Every piece has a priority and may have a shorter form. When a line is too wide,
-// the least important pieces shorten first, then leave, one at a time, until it fits. Regions that
-// share a line (the left and right of a border) compete for the same width, so an unimportant piece on
-// the right leaves before an important one on the left.
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 export interface Piece {
 	text: string;
-	/** A shorter form, used before the piece is dropped. */
 	compact?: string | undefined;
-	/** Higher stays longer. */
 	priority: number;
 }
 
 export interface FitOptions {
 	separator: string;
-	/** Width a region costs on top of its pieces when it has any, like the padding around it. */
 	regionOverhead?: number;
 	ellipsis?: string;
 }
@@ -27,7 +20,6 @@ interface Slot {
 	dropped: boolean;
 }
 
-/** One string per region, each the kept pieces joined by the separator. */
 export function fitRegions(
 	regions: readonly (readonly Piece[])[],
 	width: number,
@@ -53,7 +45,6 @@ export function fitRegions(
 	const joined = join(regions.length, slots, options.separator);
 	if (measure() <= width) return joined;
 
-	// One piece left and still too wide: cut it, keeping the overhead of its region.
 	const overhead = options.regionOverhead ?? 0;
 	return joined.map((text) =>
 		text === ""
@@ -62,7 +53,6 @@ export function fitRegions(
 	);
 }
 
-/** A single run of pieces, as one string. */
 export function fitLine(pieces: readonly Piece[], width: number, options: FitOptions): string {
 	return fitRegions([pieces], width, options)[0] ?? "";
 }

package/src/render/format.ts

@@ -1,31 +1,22 @@
-// Numbers as a person reads them at a glance. Pure, so every rule here has a test.
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
-/**
- * The widest each kind of number gets in normal use. A value is padded to its cell, so a number that
- * ticks from `9.8` to `114` to `2.8k` does not push the rest of the line around.
- */
 export const CELL = {
 	count: 4,
 	rate: 4,
 	latency: 5,
-	/** `0:08` to `9:59`, then one more for `59:59`. */
 	clock: 4,
 	percent: 4,
 	money: 6,
 } as const;
 
-/** Right-aligned in a cell of `width` columns. Longer values keep their length. */
 export function cell(text: string, width: number): string {
 	return " ".repeat(Math.max(0, width - visibleWidth(text))) + text;
 }
 
-/** What a cell shows before its value is known, so the cell is there from the start. */
 export const UNKNOWN = "–";
 
-/** `1.2k`, `43k`, `1.2M`, `22M`, the way pi writes token counts. */
 export function count(value: number): string {
 	const n = Math.max(0, Math.round(value));
 	if (n < 1000) return String(n);
@@ -35,13 +26,11 @@ export function count(value: number): string {
 	return `${Math.round(n / 1_000_000)}M`;
 }
 
-/** A speed: `42`, `906`, `1.2k`, `48k` tokens per second. */
 export function rate(perSecond: number): string {
 	if (perSecond < 10) return trim(perSecond.toFixed(1));
 	return count(perSecond);
 }
 
-/** `2m 17s`, `1h 4m`, for how long something has been running. */
 export function duration(milliseconds: number): string {
 	const total = Math.max(0, Math.floor(milliseconds / 1000));
 	const secs = total % 60;
@@ -52,7 +41,6 @@ export function duration(milliseconds: number): string {
 	return `${secs}s`;
 }
 
-/** `0:08`, `2:17`, `1:04:09`: a stopwatch, which keeps its shape as it counts. */
 export function stopwatch(milliseconds: number): string {
 	const total = Math.max(0, Math.floor(milliseconds / 1000));
 	const secs = String(total % 60).padStart(2, "0");
@@ -61,14 +49,12 @@ export function stopwatch(milliseconds: number): string {
 	return hours > 0 ? `${hours}:${String(minutes).padStart(2, "0")}:${secs}` : `${minutes}:${secs}`;
 }
 
-/** `320ms`, `1.7s`, `12s`, for latencies, where the fraction matters under ten seconds. */
 export function latency(milliseconds: number): string {
 	if (milliseconds < 1000) return `${Math.round(milliseconds)}ms`;
 	if (milliseconds < 10_000) return `${(milliseconds / 1000).toFixed(1)}s`;
 	return duration(milliseconds);
 }
 
-/** Three decimals while it is cents, two once it is dollars. */
 export function money(amount: number): string {
 	return amount >= 10 ? `$${amount.toFixed(2)}` : `$${amount.toFixed(3)}`;
 }
@@ -77,7 +63,6 @@ export function percent(value: number): string {
 	return value >= 10 || value === 0 ? `${Math.round(value)}%` : `${value.toFixed(1)}%`;
 }
 
-/** `~` for the home folder, and the tail kept when it is long, since the tail says where you are. */
 export function shortenPath(cwd: string, home: string | undefined, maxWidth: number): string {
 	const full = home === undefined ? cwd : underHome(cwd, home);
 	if (maxWidth <= 0 || visibleWidth(full) <= maxWidth) return full;
@@ -97,13 +82,11 @@ export function basename(cwd: string): string {
 	return cwd.split(/[\\/]/).findLast(Boolean) ?? cwd;
 }
 
-/** A gauge of `cells`, filled to `value` out of 100. */
 export function gauge(value: number, cells: number): { filled: number; empty: number } {
 	const filled = Math.max(0, Math.min(cells, Math.round((value / 100) * cells)));
 	return { filled, empty: cells - filled };
 }
 
-/** Clip to the start, keeping the end: for the tail of a thought, which is the newest part. */
 export function truncateTail(text: string, maxWidth: number): string {
 	if (maxWidth <= 0) return "";
 	if (visibleWidth(text) <= maxWidth) return text;

package/src/render/frame.ts

@@ -1,5 +1,3 @@
-// Borders with something written in them: `╭─ left ────── right ─╮`. The frame is the one place
-// that knows the box characters, so a new style is one entry here.
 import { visibleWidth } from "@earendil-works/pi-tui";
 
 import { type FitOptions, fitRegions, type Piece } from "./fit.ts";
@@ -40,7 +38,6 @@ export const BOXES: Record<FrameStyle, BoxChars> = {
 		horizontal: "━",
 		vertical: "┃",
 	},
-	// Only the horizontal rules, the way pi draws its editor, with the data written into them.
 	line: {
 		topLeft: "─",
 		topRight: "─",
@@ -54,23 +51,14 @@ export const BOXES: Record<FrameStyle, BoxChars> = {
 export interface BorderOptions extends Pick<FitOptions, "separator" | "ellipsis"> {
 	box: BoxChars;
 	edge: "top" | "bottom";
-	/** Paints the rule and the corners. */
 	paint: (text: string) => string;
-	/**
-	 * Text that follows the left pieces and takes whatever room is left, like the working spinner.
-	 * It goes after them because it changes width all the time, and the pieces must not move.
-	 */
 	lead?: ((budget: number) => string | undefined) | undefined;
-	/** Room kept for the lead, so the pieces never squeeze it out. */
 	leadMin?: number;
 }
 
-/** Corners, one rule cell each side, and one rule cell between the two regions at least. */
 const FIXED = 5;
-/** A space on each side of a region's text. */
 const PADDING = 2;
 
-/** One border line of exactly `width` columns, with both regions fitted into it. */
 export function border(
 	width: number,
 	left: readonly Piece[],

package/src/render/glyphs.ts

@@ -1,5 +1,3 @@
-// One glyph per kind of data, in three sets. Nerd Font glyphs live in the private use area, so they
-// are written as escapes: a font without them shows a box, and a reviewer sees which code point it is.
 export type IconMode = "auto" | "nerd" | "unicode" | "ascii";
 export type IconSet = Exclude<IconMode, "auto">;
 
@@ -31,10 +29,8 @@ export interface Glyphs {
 	untracked: string;
 	conflicted: string;
 	stashed: string;
-	/** Full and empty cells of a gauge. Blocks, so the gauge never reads as part of a border rule. */
 	fill: string;
 	empty: string;
-	/** Six rising bars, one per effort level from minimal to max. */
 	levels: readonly string[];
 	ellipsis: string;
 }
@@ -77,7 +73,6 @@ export const NERD: Glyphs = {
 	ellipsis: "…",
 };
 
-/** Symbols every monospace font with decent Unicode coverage has, all one column wide. */
 export const UNICODE: Glyphs = {
 	...COMMON,
 	set: "unicode",
@@ -141,10 +136,6 @@ export const ASCII: Glyphs = {
 
 const SETS: Record<IconSet, Glyphs> = { nerd: NERD, unicode: UNICODE, ascii: ASCII };
 
-/**
- * Auto trusts a local UTF-8 terminal to have a Nerd Font. Over SSH the font lives on the other
- * machine, so it drops to plain Unicode, and a terminal that does not speak UTF-8 gets ASCII.
- */
 export function resolveIcons(mode: IconMode, env: NodeJS.ProcessEnv = process.env): Glyphs {
 	if (mode !== "auto") return SETS[mode];
 	if (env.TERM === "dumb") return ASCII;

package/src/render/paint.ts

@@ -1,9 +1,5 @@
-// Colour, without a single colour value. Every role names a token of the active pi theme, so the look
-// follows whatever theme is on: the built-in ones, a custom JSON, or the desktop palette this package
-// writes from matugen. Change the theme and every piece moves with it.
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 
-/** What a piece of text is. The table below says which theme token paints it. */
 export type Role =
 	| "path"
 	| "branch"
@@ -29,10 +25,6 @@ export type Role =
 	| "clock"
 	| "brand";
 
-/**
- * The palette, as theme tokens. Syntax tokens are borrowed on purpose: a theme spends its hues there,
- * so they give the line variety that stays in the theme's family.
- */
 export const ROLE_TOKENS: Record<Role, ThemeColor> = {
 	path: "accent",
 	branch: "syntaxFunction",
@@ -59,7 +51,6 @@ export const ROLE_TOKENS: Record<Role, ThemeColor> = {
 	brand: "accent",
 };
 
-/** Pi gives every effort level its own token, which a theme draws as a ramp from cool to hot. */
 const EFFORT_TOKENS: Record<string, ThemeColor> = {
 	off: "thinkingOff",
 	minimal: "thinkingMinimal",
@@ -73,21 +64,15 @@ const EFFORT_TOKENS: Record<string, ThemeColor> = {
 export const EFFORT_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
 export interface Paint {
-	/** Separators, units and labels sit back, so the data reads first. */
 	dim(text: string): string;
-	/** Quieter data. */
 	muted(text: string): string;
 	text(text: string): string;
 	bold(text: string): string;
 	italic(text: string): string;
 	role(role: Role, text: string): string;
-	/** The colour of one effort level. */
 	effort(level: string, text: string): string;
-	/** Calm under half, warm past 70%, alarming past 90%. */
 	stress(percent: number, text: string): string;
-	/** Money reads calm until it adds up. */
 	money(amount: number, text: string): string;
-	/** The editor frame, which pi recolours with the effort level and for bash mode. */
 	frame(text: string): string;
 }
 
@@ -118,7 +103,6 @@ function moneyToken(amount: number): ThemeColor {
 	return ROLE_TOKENS.cost;
 }
 
-/** Used by tests and by anything drawing without a theme. */
 export const PLAIN: Paint = {
 	dim: identity,
 	muted: identity,