pi-zen 0.1.1 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ I built `pi-zen` because I wanted a minimal interface that made it easier to sta
 
 For real knowledge work, I like being an active participant. I want to understand what is happening between the AI and me so we can be good partners in making decisions. `pi-zen` gives me that space: clear responses, visible progress, and the useful parts of the session in a calm, visually appealing interface.
 
-`pi-zen` is a presentation extension for the [Pi](https://pi.dev) terminal interface. It removes visual clutter while preserving conversations, tool activity, reasoning, and session data. It adds compact tool summaries and diffs, a minimal editor rail, a quieter startup, and a calmer working indicator without changing tool execution or model prompts.
+`pi-zen` is a presentation extension for the [Pi](https://pi.dev) terminal interface. It removes visual clutter while preserving conversations, tool activity, reasoning, and session data. It adds compact tool summaries and diffs, a minimal editor rail, a quieter startup, a calmer working indicator, and a live reading of where the current request's time is going, without changing tool execution or model prompts.
 
 ## Showcase
 
@@ -20,8 +20,20 @@ For real knowledge work, I like being an active participant. I want to understan
 
 ![Pi Zen coding cat demo](screenshots/pi-zen-coding-cat.gif)
 
+## While a request runs
+
+Above the editor, one dim line says where the time is going and updates as the request runs:
+
+```text
+7.2s thinking · 3.6s writing · ↑6.5k ↓5.8k
+```
+
+Thinking is the time the model spends reasoning, including the silence before it streams anything; writing is the time it spends producing text and tool calls. Time a tool spends running belongs to neither and is left out. The token counts follow Pi's footer: tokens sent, excluding cache reads and writes, and tokens produced, reasoning included. Both cover the whole request, however many turns it takes. A half of the work that took no measurable time is left out, so a model that does not stream its reasoning simply reads as writing. The final reading stays until the next request starts.
+
 ## Quick start
 
+Requires Pi 0.84.3 or newer.
+
 Install the extension from npm:
 
 ```sh

package/extensions/zen.ts

@@ -16,6 +16,7 @@ import { type BuiltinToolOptions, registerCompactTools } from "../src/compact-to
 import { squeezeBlankLines } from "../src/markdown-compaction.ts";
 import { installBlankHeader } from "../src/silent-header.ts";
 import { thinkingTail, thinkingTailLineBudget } from "../src/thinking-tail.ts";
+import { TurnStatus } from "../src/turn-status.ts";
 import { installQuietIndicator, restoreDefaultIndicator } from "../src/working-indicator.ts";
 import { ZenEditor } from "../src/zen-editor.ts";
 
@@ -63,6 +64,7 @@ export default function zen(pi: ExtensionAPI): void {
 	let deferredThemeProjection: ReturnType<typeof setTimeout> | undefined;
 	let activeContext: ExtensionContext | undefined;
 	const grouper = new CallGrouper();
+	const turnStatus = new TurnStatus();
 
 	// Installing is idempotent on purpose: another extension can take the header
 	// or the editor at any time, so `/zen on` has to be able to claim them back.
@@ -122,6 +124,7 @@ export default function zen(pi: ExtensionAPI): void {
 		ctx.ui.setHeader(undefined);
 		ctx.ui.setEditorComponent(state.previousEditor);
 		restoreDefaultIndicator(ctx.ui);
+		turnStatus.clear(ctx);
 		state = { kind: "off" };
 	};
 
@@ -147,6 +150,28 @@ export default function zen(pi: ExtensionAPI): void {
 		}
 	});
 
+	const zenActive = (ctx: ExtensionContext) => state.kind === "on" && ctx.mode === "tui";
+
+	pi.on("agent_start", (_event, ctx) => {
+		if (zenActive(ctx)) turnStatus.begin(ctx);
+	});
+
+	pi.on("message_start", (event, ctx) => {
+		if (zenActive(ctx)) turnStatus.open(event, ctx);
+	});
+
+	pi.on("message_update", (event, ctx) => {
+		if (zenActive(ctx)) turnStatus.update(event, ctx);
+	});
+
+	pi.on("message_end", (event, ctx) => {
+		if (zenActive(ctx)) turnStatus.commit(event, ctx);
+	});
+
+	pi.on("agent_end", (_event, ctx) => {
+		if (zenActive(ctx)) turnStatus.end(ctx);
+	});
+
 	pi.on("turn_end", () => {
 		// The next turn's reads belong to their own line, not to this turn's.
 		grouper.close();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-zen",
-	"version": "0.1.1",
+	"version": "0.2.0",
 	"description": "A quiet Pi TUI on one switch: backgroundless messages, a rail editor, compact tool calls, and restrained reasoning",
 	"type": "module",
 	"packageManager": "pnpm@11.21.0",
@@ -46,12 +46,12 @@
 		]
 	},
 	"peerDependencies": {
-		"@earendil-works/pi-coding-agent": "*",
-		"@earendil-works/pi-tui": "*"
+		"@earendil-works/pi-coding-agent": ">=0.84.3",
+		"@earendil-works/pi-tui": ">=0.84.3"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-coding-agent": "0.84.3",
-		"@earendil-works/pi-tui": "0.84.3",
+		"@earendil-works/pi-coding-agent": "0.85.0",
+		"@earendil-works/pi-tui": "0.85.0",
 		"@oxlint/plugins": "^1.79.0",
 		"@types/node": "^24.10.0",
 		"oxlint": "^1.79.0",

package/src/backgroundless-theme.ts

@@ -1,4 +1,4 @@
-import { Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 
 /** Name used only while Zen's backgroundless projection is active. */
 export const BACKGROUNDLESS_THEME_NAME = "pi-zen:backgroundless";
@@ -53,11 +53,14 @@ const THEME_COLORS = [
 	"bashMode",
 ] as const satisfies ReadonlyArray<ThemeColor>;
 
-type ThemeBackground = Parameters<Theme["bg"]>[0];
+type ThemeBackground = Parameters<Theme["bg"]>[0] | "scrollbarThumb";
+
+type LegacyScrollbarTheme = {
+	readonly getBgAnsi: (color: ThemeBackground) => string;
+};
 
 const THEME_BACKGROUNDS = [
 	"selectedBg",
-	"scrollbarThumb",
 	"searchMatchBg",
 	"userMessageBg",
 	"customMessageBg",
@@ -98,11 +101,32 @@ function emptyBackgrounds(): BackgroundInput {
 	return Object.fromEntries(THEME_BACKGROUNDS.map((color) => [color, ""])) as BackgroundInput;
 }
 
+function captureScrollbarColors(
+	source: Theme,
+	foregroundAnsi: Map<ThemeColor, string>,
+	backgroundAnsi: Map<ThemeBackground, string>,
+): void {
+	let thumb: string;
+	try {
+		thumb = source.getFgAnsi("scrollbarThumb");
+	} catch (error) {
+		if (!(error instanceof Error) || error.message !== "Unknown theme color: scrollbarThumb") throw error;
+		// SAFETY: Pi 0.84.x reports this missing foreground because its thumb is a background token.
+		// The current Theme type omits that legacy key; its getter still checks the key at runtime.
+		const legacySource = source as LegacyScrollbarTheme;
+		backgroundAnsi.set("scrollbarThumb", legacySource.getBgAnsi("scrollbarThumb"));
+		return;
+	}
+	foregroundAnsi.set("scrollbarThumb", thumb);
+	foregroundAnsi.set("scrollbarTrack", source.getFgAnsi("scrollbarTrack"));
+}
+
 function makeThemeSnapshot(source: Theme, options: ThemeSnapshotOptions): Theme {
 	const foregroundAnsi = new Map<ThemeColor, string>();
 	const backgroundAnsi = new Map<ThemeBackground, string>();
 	for (const color of THEME_COLORS) foregroundAnsi.set(color, source.getFgAnsi(color));
 	for (const color of THEME_BACKGROUNDS) backgroundAnsi.set(color, source.getBgAnsi(color));
+	captureScrollbarColors(source, foregroundAnsi, backgroundAnsi);
 
 	// SAFETY: Pi created source, so its constructor is the runtime's Theme constructor. Using that exact constructor
 	// keeps instanceof checks valid when this source package has a different development copy of Pi installed.
@@ -120,16 +144,17 @@ function makeThemeSnapshot(source: Theme, options: ThemeSnapshotOptions): Theme
 		if (ansi === undefined) throw new Error(`Unknown theme color: ${color}`);
 		return ansi;
 	};
-	snapshot.getBgAnsi = (color: ThemeBackground): string => {
+	const getBgAnsi = (color: ThemeBackground): string => {
 		if (options.suppressContentBackgrounds && CONTENT_BACKGROUNDS.has(color)) return "\x1b[49m";
 		const ansi = backgroundAnsi.get(color);
 		if (ansi === undefined) throw new Error(`Unknown theme background: ${color}`);
 		return ansi;
 	};
+	snapshot.getBgAnsi = getBgAnsi;
 	snapshot.fg = (color: ThemeColor, text: string): string => `${snapshot.getFgAnsi(color)}${text}\x1b[39m`;
 	snapshot.bg = (color: ThemeBackground, text: string): string => {
 		if (options.suppressContentBackgrounds && CONTENT_BACKGROUNDS.has(color)) return text;
-		return `${snapshot.getBgAnsi(color)}${text}\x1b[49m`;
+		return `${getBgAnsi(color)}${text}\x1b[49m`;
 	};
 
 	return snapshot;
@@ -148,7 +173,7 @@ export function snapshotTheme(source: Theme): Theme {
 /**
  * Keep the active theme while removing message and tool backgrounds.
  * Surface-specific body text falls back to the theme's terminal-safe base text;
- * selection, search, and scrollbar backgrounds remain as affordances.
+ * selection and search backgrounds, plus scrollbar colors, remain as affordances.
  *
  * @param source - Pi's currently active theme.
  * @returns A backgroundless projection of the active theme.

package/src/turn-status.ts

@@ -0,0 +1,101 @@
+import type {
+	ExtensionContext,
+	MessageEndEvent,
+	MessageStartEvent,
+	MessageUpdateEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import { advance, beginRun, formatTurnStatus, type TurnPhase, type TurnTiming, type TurnTokens } from "./turn-timing.ts";
+import { QUIET_INTERVAL_MS } from "./working-indicator.ts";
+
+const WIDGET_KEY = "zen-turn-status";
+const WIDGET_INDENT = 1;
+const FALLBACK_COLUMNS = 80;
+
+type StreamedMessage = Extract<MessageUpdateEvent["message"], { role: "assistant" }>;
+
+function tokensOf(message: StreamedMessage): TurnTokens {
+	return { input: message.usage.input, output: message.usage.output };
+}
+
+function phaseOf(message: StreamedMessage): TurnPhase | undefined {
+	const latest = message.content.at(-1);
+	if (latest === undefined) return undefined;
+	return latest.type === "thinking" ? "thinking" : "writing";
+}
+
+export class TurnStatus {
+	private timing: TurnTiming = beginRun();
+	private ticker: ReturnType<typeof setInterval> | undefined;
+	private context: ExtensionContext | undefined;
+
+	begin(ctx: ExtensionContext): void {
+		this.context = ctx;
+		this.timing = beginRun();
+		this.startTicking();
+		this.render();
+	}
+
+	open(event: MessageStartEvent, ctx: ExtensionContext): void {
+		if (event.message.role !== "assistant") return;
+
+		this.context = ctx;
+		this.timing = advance(this.timing, { kind: "opened" }, Date.now());
+		this.render();
+	}
+
+	update(event: MessageUpdateEvent, ctx: ExtensionContext): void {
+		if (event.message.role !== "assistant") return;
+
+		this.context = ctx;
+		const phase = phaseOf(event.message);
+		if (phase !== undefined) {
+			const live = tokensOf(event.message);
+			this.timing = advance(this.timing, { kind: "producing", phase, live }, Date.now());
+		}
+		this.render();
+	}
+
+	commit(event: MessageEndEvent, ctx: ExtensionContext): void {
+		if (event.message.role !== "assistant") return;
+
+		this.context = ctx;
+		this.timing = advance(this.timing, { kind: "settled", tokens: tokensOf(event.message) }, Date.now());
+		this.render();
+	}
+
+	end(ctx: ExtensionContext): void {
+		this.context = ctx;
+		this.timing = advance(this.timing, { kind: "closed" }, Date.now());
+		this.stopTicking();
+		this.render();
+	}
+
+	clear(ctx: ExtensionContext): void {
+		this.context = ctx;
+		this.timing = beginRun();
+		this.stopTicking();
+		ctx.ui.setWidget(WIDGET_KEY, undefined);
+	}
+
+	private startTicking(): void {
+		this.stopTicking();
+		this.ticker = setInterval(() => this.render(), QUIET_INTERVAL_MS);
+		this.ticker.unref();
+	}
+
+	private stopTicking(): void {
+		if (this.ticker === undefined) return;
+		clearInterval(this.ticker);
+		this.ticker = undefined;
+	}
+
+	private render(): void {
+		const ctx = this.context;
+		if (ctx === undefined) return;
+
+		const columns = process.stdout.columns ?? FALLBACK_COLUMNS;
+		const line = formatTurnStatus(this.timing, Date.now(), columns - WIDGET_INDENT);
+		ctx.ui.setWidget(WIDGET_KEY, line === "" ? undefined : [ctx.ui.theme.fg("muted", line)]);
+	}
+}

package/src/turn-timing.ts

@@ -0,0 +1,144 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+export type TurnPhase = "thinking" | "writing";
+
+export type TurnTokens = {
+	readonly input: number;
+	readonly output: number;
+};
+
+type Accrued = {
+	readonly thinkingMs: number;
+	readonly writingMs: number;
+	readonly committed: TurnTokens;
+};
+
+export type TurnTiming =
+	| ({ readonly kind: "idle" } & Accrued)
+	| ({
+			readonly kind: "waiting";
+			readonly openedAt: number;
+			readonly live: TurnTokens;
+	  } & Accrued)
+	| ({
+			readonly kind: "streaming";
+			readonly phase: TurnPhase;
+			readonly since: number;
+			readonly live: TurnTokens;
+	  } & Accrued);
+
+export type TurnSignal =
+	| { readonly kind: "opened" }
+	| { readonly kind: "producing"; readonly phase: TurnPhase; readonly live: TurnTokens }
+	| { readonly kind: "closed" }
+	| { readonly kind: "settled"; readonly tokens: TurnTokens };
+
+type TurnElapsed = {
+	readonly thinkingMs: number;
+	readonly writingMs: number;
+};
+
+const SEPARATOR = " · ";
+const ELLIPSIS = "…";
+const LEGIBLE_MS = 50;
+const NO_TOKENS: TurnTokens = { input: 0, output: 0 };
+
+function formatSeconds(ms: number): string {
+	return `${(Math.max(0, ms) / 1000).toFixed(1)}s`;
+}
+
+function formatTokenCount(count: number): string {
+	if (count < 1_000) return String(Math.max(0, Math.round(count)));
+	if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1_000)}k`;
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(count / 1_000_000)}M`;
+}
+
+function addTokens(left: TurnTokens, right: TurnTokens): TurnTokens {
+	return { input: left.input + right.input, output: left.output + right.output };
+}
+
+function settle(timing: TurnTiming, now: number, waitPhase: TurnPhase): Accrued {
+	const totals = { thinkingMs: timing.thinkingMs, writingMs: timing.writingMs, committed: timing.committed };
+	if (timing.kind === "idle") return totals;
+
+	const spent = Math.max(0, now - (timing.kind === "waiting" ? timing.openedAt : timing.since));
+	const phase = timing.kind === "waiting" ? waitPhase : timing.phase;
+
+	return phase === "thinking"
+		? { ...totals, thinkingMs: totals.thinkingMs + spent }
+		: { ...totals, writingMs: totals.writingMs + spent };
+}
+
+function settleAsThinking(timing: TurnTiming, now: number): Accrued {
+	return settle(timing, now, "thinking");
+}
+
+function elapsed(timing: TurnTiming, now: number): TurnElapsed {
+	const totals = settleAsThinking(timing, now);
+	return { thinkingMs: totals.thinkingMs, writingMs: totals.writingMs };
+}
+
+function tokens(timing: TurnTiming): TurnTokens {
+	return timing.kind === "idle" ? timing.committed : addTokens(timing.committed, timing.live);
+}
+
+function statusSegments(timing: TurnTiming, now: number): string[] {
+	const spent = elapsed(timing, now);
+	const used = tokens(timing);
+
+	const segments: string[] = [];
+	if (spent.thinkingMs >= LEGIBLE_MS) segments.push(`${formatSeconds(spent.thinkingMs)} thinking`);
+	if (spent.writingMs >= LEGIBLE_MS) segments.push(`${formatSeconds(spent.writingMs)} writing`);
+	if (used.input > 0 || used.output > 0) {
+		segments.push(`↑${formatTokenCount(used.input)} ↓${formatTokenCount(used.output)}`);
+	}
+	return segments;
+}
+
+function fitToWidth(segments: string[], width: number): string {
+	let kept = segments.length;
+	while (kept > 1 && visibleWidth(segments.slice(0, kept).join(SEPARATOR)) > width) kept -= 1;
+
+	const body = segments.slice(0, kept).join(SEPARATOR);
+	return visibleWidth(body) <= width ? body : truncateToWidth(body, width, ELLIPSIS);
+}
+
+export function beginRun(): TurnTiming {
+	return { kind: "idle", thinkingMs: 0, writingMs: 0, committed: NO_TOKENS };
+}
+
+export function advance(timing: TurnTiming, signal: TurnSignal, now: number): TurnTiming {
+	switch (signal.kind) {
+		case "opened":
+			return { kind: "waiting", openedAt: now, live: NO_TOKENS, ...settleAsThinking(timing, now) };
+
+		case "producing": {
+			if (timing.kind === "streaming" && timing.phase === signal.phase) return { ...timing, live: signal.live };
+
+			return {
+				kind: "streaming",
+				phase: signal.phase,
+				since: now,
+				live: signal.live,
+				...settle(timing, now, signal.phase),
+			};
+		}
+
+		case "closed":
+			return { kind: "idle", ...settleAsThinking(timing, now) };
+
+		case "settled": {
+			const totals = settleAsThinking(timing, now);
+			return { kind: "idle", ...totals, committed: addTokens(totals.committed, signal.tokens) };
+		}
+	}
+}
+
+export function formatTurnStatus(timing: TurnTiming, now: number, width: number): string {
+	if (width <= 0) return "";
+
+	const segments = statusSegments(timing, now);
+	return segments.length === 0 ? "" : fitToWidth(segments, width);
+}