@adeildo/pi-look 4.0.0 → 5.0.0

package/README.md

@@ -20,24 +20,24 @@ It also comes in [`@adeildo/pi-harness`](../harness), with the rest of the piece
 
 **The strip above the editor** is calm on purpose: nothing in it moves while the model streams except the stopwatch.
 
-| Piece                              | Means                                                                                                                            |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `0:12 · 3 calls`                   | How long the agent has worked on this prompt, and how many calls to the model it made                                            |
-| `last call 1.7s wait · ↓906 tok/s` | The last call that finished: how long it waited for the first token, and how fast it wrote. Final numbers, never a partial count |
+| Piece                                            | Means                                                                                                                                                          |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `0:12  3 calls`                                  | How long the agent has worked on this prompt, and how many calls to the model it made                                                                          |
+| `last call 1.7s wait  900ms thought  ↓906 tok/s` | The last call that finished: how long the model took to start, how long it thought before writing, and how fast it wrote. Final numbers, never a partial count |
 
-The live pieces, which move with every token, go in any slot too: `speed`, `wait`, `request` and `costRate`.
+The wait runs from the moment the request leaves, which pi reports on `before_provider_request`, to the first token of any kind. `thought` is the part of that wait spent thinking before the first word, and only appears when the model thought. The pieces that split it further, `server` (the request leaving to the response headers, which is the provider's own latency) and `prefill` (the headers to the first token, the model reading the prompt), go in any slot. So do the live pieces, which move with every token: `speed`, `wait`, `request` and `costRate`.
 
-The arrows are from where you sit: `↑ in` is what goes to the model, `↓ out` is what comes back. `/look explain` lists every piece on screen with its current value and what it means.
+The arrows are from where you sit: `↑ in` is what goes to the model, `↓ out` is what comes back. `What is on screen`, in the Slots section of the settings (`Alt+S`), lists every piece with its current value and what it means.
 
 **The frame** has four slots. By default: the branch with its distance and changes on the top left, after the spinner; the folder and the machine on the top right; the permission mode, the model and the effort meter on the bottom left; the context on the bottom right. The border is drawn in pi's own effort colour, so it warms up as the model thinks harder, and turns to the bash colour in shell mode.
 
-**The spinner** says what is happening instead of "Working": the newest line of the thinking, the tool call being written, or the command running with its first argument (`bash · git status`, `edit · src/index.ts`).
+**The spinner** names the state instead of saying "Working": `waiting` for the first token, `thinking`, `writing`, `drafting bash` while the model writes the call, `running bash` while it runs. The thinking and the call are already in the transcript, so the spinner never repeats them.
 
 **The footer** is the session: the cost (`sub` when the figure is what a subscription would have paid), tokens sent and received, where sent counts the cached part too, the cache hit of the last prompt, the average speeds of the whole session, and last, what other packages report, because it changes the most.
 
 ### It holds still
 
-Numbers change on every frame, and the screen must not move with them. Every number sits in a cell of fixed width (`  17` and `2.8k` take the same room), a value that is not known yet shows as `–` in its cell instead of appearing later in the middle of the line, the working time is a stopwatch (`0:59`, `1:00`) instead of `59s` then `1m 0s`, and an estimate is drawn quieter instead of gaining a `~`. The spinner's message, which grows with every token of thinking, comes after the branch and only takes the room the slots leave. The strip and the footer keep their line from the start, so the editor does not jump when the first answer arrives.
+Numbers change on every frame, and the screen must not move with them. Every number sits in a cell of fixed width (`  17` and `2.8k` take the same room), a value that is not known yet shows as `–` in its cell instead of appearing later in the middle of the line, the working time is a stopwatch (`0:59`, `1:00`) instead of `59s` then `1m 0s`, and an estimate is drawn quieter instead of gaining a `~`. The spinner's message comes after the branch and only takes the room the slots leave. The strip and the footer keep their line from the start, so the editor does not jump when the first answer arrives.
 
 Every finished answer leaves a small entry in the session with its time to first token and writing time, because pi records usage without a duration. That is what keeps the averages right after a resume.
 
@@ -70,10 +70,7 @@ If you run [DankMaterialShell](https://github.com/AvengeMedia/DankMaterialShell)
 
 Pi's own `system` theme builds its colours from the terminal's palette. If your terminal already follows matugen, `system` gets close without this, with fewer colours to work from: the sixteen terminal colours instead of the Material roles.
 
-```
-/look explain    what every piece on screen is, with its current value
-/look theme      write the desktop theme and switch to it
-```
+`Switch to it now`, in the Desktop theme section of the settings (`Alt+S`), writes the theme and makes it pi's.
 
 The mapping, from the Material roles and the terminal colours:
 
@@ -97,25 +94,25 @@ Another palette source is a new file next to `src/desktop/palette.ts`: a parser
 
 They live in the file every piece shares, `~/.pi/agent/extensions/pi-harness/settings.json`, under `look.`. The ones marked _project_ are also read from a trusted project.
 
-| Key                 | Default                                                | Does                                                                                                                                                             |
-| ------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `strip`             | `["elapsed", "last"]`                                  | The line above the editor. _project_                                                                                                                             |
-| `frame.topLeft`     | `["branch", "session"]`                                | After the spinner. _project_                                                                                                                                     |
-| `frame.topRight`    | `["path", "host"]`                                     | _project_                                                                                                                                                        |
-| `frame.bottomLeft`  | `["status:pi-ask-permission:mode", "model", "effort"]` | _project_                                                                                                                                                        |
-| `frame.bottomRight` | `["context"]`                                          | _project_                                                                                                                                                        |
-| `below`             | `["cost", "tokens", "cache", "average", "statuses"]`   | The line below the editor. _project_                                                                                                                             |
-| `labels`            | `true`                                                 | A short word before each number: `out`, `in`, `ttft`, `time`, `ctx`, `cache`. Off is denser, with only the glyphs. _project_                                     |
-| `frame.style`       | `"rounded"`                                            | `rounded`, `square`, `heavy`, `line` (pi's two rules, written into), or `off`, which leaves pi's editor alone and moves the frame slots to the footer. _project_ |
-| `frame.cursor`      | `"bar"`                                                | `block`, `bar` or `underline`. The last two use the terminal's own cursor                                                                                        |
-| `header`            | `"card"`                                               | `card`, `compact` (two lines) or `off` (pi's own). _project_                                                                                                     |
-| `icons`             | `"auto"`                                               | `nerd`, `unicode` or `ascii`. Auto uses Nerd Font glyphs locally and plain Unicode over SSH, where the font lives on the other machine                           |
-| `separator`         | `"dot"`                                                | `dot`, `bar`, `slash` or `space`. _project_                                                                                                                      |
-| `pathLength`        | `40`                                                   | Longest the folder may be before it loses folders from the left. _project_                                                                                       |
-| `gaugeCells`        | `8`                                                    | Cells in the context gauge. `0` hides it. _project_                                                                                                              |
-| `peek`              | `true`                                                 | The spinner says what runs. Off, it says what pi says                                                                                                            |
-| `desktop.theme`     | `true`                                                 | Keep the desktop theme written. Nothing happens without the palette file                                                                                         |
-| `desktop.source`    | `"~/.cache/DankMaterialShell/dms-colors.json"`         | Where the palette is                                                                                                                                             |
+| Key                 | Default                                                                               | Does                                                                                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `strip`             | `["elapsed", "last"]`                                                                 | The line above the editor. _project_                                                                                                                             |
+| `frame.topLeft`     | `["branch", "session"]`                                                               | After the spinner. _project_                                                                                                                                     |
+| `frame.topRight`    | `["path", "host"]`                                                                    | _project_                                                                                                                                                        |
+| `frame.bottomLeft`  | `["status:pi-ask-permission:mode", "model", "status:pi-providers:account", "effort"]` | _project_                                                                                                                                                        |
+| `frame.bottomRight` | `["context"]`                                                                         | _project_                                                                                                                                                        |
+| `below`             | `["cost", "tokens", "cache", "average", "statuses"]`                                  | The line below the editor. _project_                                                                                                                             |
+| `labels`            | `true`                                                                                | A short word before each number: `out`, `in`, `ttft`, `wait`, `thought`, `server`, `time`, `ctx`, `cache`. Off is denser, with only the glyphs. _project_        |
+| `frame.style`       | `"rounded"`                                                                           | `rounded`, `square`, `heavy`, `line` (pi's two rules, written into), or `off`, which leaves pi's editor alone and moves the frame slots to the footer. _project_ |
+| `frame.cursor`      | `"bar"`                                                                               | `block`, `bar` or `underline`. The last two use the terminal's own cursor                                                                                        |
+| `header`            | `"card"`                                                                              | `card`, `compact` (two lines) or `off` (pi's own). _project_                                                                                                     |
+| `icons`             | `"auto"`                                                                              | `nerd`, `unicode` or `ascii`. Auto uses Nerd Font glyphs locally and plain Unicode over SSH, where the font lives on the other machine                           |
+| `separator`         | `"space"`                                                                             | `dot`, `bar`, `slash` or `space`. _project_                                                                                                                      |
+| `pathLength`        | `40`                                                                                  | Longest the folder may be before it loses folders from the left. _project_                                                                                       |
+| `gaugeCells`        | `8`                                                                                   | Cells in the context gauge. `0` hides it. _project_                                                                                                              |
+| `peek`              | `true`                                                                                | The spinner names the state. Off, it says what pi says                                                                                                           |
+| `desktop.theme`     | `true`                                                                                | Keep the desktop theme written. Nothing happens without the palette file                                                                                         |
+| `desktop.source`    | `"~/.cache/DankMaterialShell/dms-colors.json"`                                        | Where the palette is                                                                                                                                             |
 
 ### Segments
 
@@ -135,8 +132,9 @@ Any segment goes in any slot, in the order the slot lists them.
 | `context`      | Context used, the gauge, tokens over the window                                                       |
 | `speed`        | This answer's speeds, received `↓` and sent `↑`                                                       |
 | `wait`         | Time to the first token                                                                               |
+| `server`       | The last call's time from the request leaving to the response headers                                 |
 | `elapsed`      | The agent's working time, as a stopwatch, and its calls                                               |
-| `last`         | The last finished call: wait for the first token and writing speed                                    |
+| `last`         | The last finished call: its wait, its thought time and its writing speed                              |
 | `request`      | This answer's tokens, with the cache                                                                  |
 | `costRate`     | This answer's cost per million tokens                                                                 |
 | `cost`         | The session's cost                                                                                    |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@adeildo/pi-look",
-	"version": "4.0.0",
+	"version": "5.0.0",
 	"description": "Pi's start screen, a framed editor and the footer, redrawn around the data that matters and painted only with the theme's colours.",
 	"keywords": [
 		"pi",
@@ -38,7 +38,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@adeildo/pi-kit": "4.0.0"
+		"@adeildo/pi-kit": "5.0.0"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/data/git.ts

@@ -1,14 +1,9 @@
-// The working tree, in one call: `git status --porcelain=v2 --branch --show-stash` says how far the
-// branch is from its upstream and what changed, file by file. The parse is pure so it can be tested
-// against captured output.
 import { execFile } from "node:child_process";
 
 export interface GitState {
 	ahead: number;
 	behind: number;
-	/** In the index, ready to commit. */
 	staged: number;
-	/** Changed in the tree and not staged. */
 	modified: number;
 	untracked: number;
 	conflicted: number;
@@ -45,7 +40,6 @@ export function parseStatus(output: string): GitState {
 	return state;
 }
 
-/** Undefined outside a repository, or when git is missing or slow. */
 export function readGit(cwd: string): Promise<GitState | undefined> {
 	return new Promise((resolve) => {
 		execFile(

package/src/data/snapshot.ts

@@ -1,5 +1,3 @@
-// Everything the look can show, read once per frame. Segments are pure functions of this, so the
-// whole screen can be drawn and tested without a terminal or a session.
 import { hostname } from "node:os";
 
 import { VERSION, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
@@ -18,7 +16,6 @@ import {
 
 export interface ModelInfo {
 	name: string;
-	/** As the provider wants to be written, not the id pi routes by. */
 	provider: string;
 	reasoning: boolean;
 }
@@ -34,7 +31,6 @@ export interface Snapshot {
 	cwd: string;
 	home: string | undefined;
 	branch: string | null;
-	/** Undefined outside a repository or before the first probe. */
 	git: GitState | undefined;
 	host: string | undefined;
 	sessionName: string | undefined;
@@ -44,16 +40,12 @@ export interface Snapshot {
 	context: ContextInfo | undefined;
 	totals: Totals;
 	cacheHit: number | undefined;
-	/** The last prompt was written to the cache and nothing was read: the first call, not a miss. */
 	cacheWarming: boolean;
-	/** The dollar figure is what the tokens would have cost, not what was billed. */
 	subscription: boolean;
 	request: RequestView | undefined;
-	/** The last request that finished: its numbers are final. */
 	last: RequestView | undefined;
 	run: RunView | undefined;
 	averages: Averages;
-	/** What other packages report through `setStatus`, by key, in key order. */
 	statuses: ReadonlyMap<string, string>;
 }
 
@@ -98,10 +90,6 @@ interface Derived {
 	averages: Averages;
 }
 
-/**
- * Reads the session once per frame. The sums walk the whole branch, so they are kept until the leaf
- * moves.
- */
 export class SnapshotReader {
 	#key: string | undefined;
 	#derived: Derived | undefined;
@@ -167,7 +155,6 @@ function contextOf(ctx: ExtensionContext): ContextInfo | undefined {
 	return { percent: usage.percent, tokens: usage.tokens, window: usage.contextWindow };
 }
 
-/** A status is one line: newlines and tabs from another package would break the frame. */
 function sanitize(text: string): string {
 	return text.replace(/[\r\n\t]+/g, " ").trim();
 }

package/src/data/telemetry.ts

@@ -1,10 +1,3 @@
-// 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,
@@ -14,42 +7,48 @@ import {
 	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;
+/** Measured over 16,889 assistant messages of one machine: 2.88 characters per output token. */
+const DEFAULT_CHARS_PER_TOKEN = 2.9;
+
+/** What a delta carried, so the wait for the first thought can be told from the first word. */
+export type DeltaKind = "thinking" | "writing";
 
 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. */
+	/** From the request leaving to the first token of any kind: what you waited for the model. */
+	waitMs: number | undefined;
+	/** The same wait while it is still running, so the number counts from the moment it left. */
+	waitingMs: number;
+	/** From the request leaving to the response headers: the provider's own latency. */
+	serverMs: number | undefined;
+	/** From the headers to the first token: the model reading the prompt. */
+	prefillMs: number | undefined;
+	/** From the first thought to the first word written. Unset when it wrote without thinking. */
+	thoughtMs: number | undefined;
 	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;
+	/** When the request left, from pi's own `before_provider_request`. */
+	sentAt: number | undefined;
+	headersAt: number | undefined;
 	firstTokenAt: number | undefined;
+	firstWritingAt: number | undefined;
 	endedAt: number | undefined;
 	usage: Totals;
-	/** Characters seen, for a live rate before the provider says how many tokens they were. */
 	characters: number;
 }
 
@@ -67,12 +66,20 @@ interface UsageLike {
 	cost: { total: number };
 }
 
+function span(from: number | undefined, to: number | undefined): number | undefined {
+	return from === undefined || to === undefined ? undefined : to - from;
+}
+
 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;
+	/** The marks of the request in flight, which arrive before the pi message it belongs to. */
+	#sentAt: number | undefined;
+	#headersAt: number | undefined;
+	/** Characters and tokens of the answers that finished, for the live estimate to use a real ratio. */
+	#sampled = { characters: 0, output: 0 };
 
 	constructor(now: () => number = Date.now) {
 		this.#now = now;
@@ -86,35 +93,43 @@ export class Telemetry {
 		if (this.#run !== undefined && this.#run.endedAt === undefined) this.#run.endedAt = this.#now();
 	}
 
-	/** A turn starting is the request leaving. */
+	/** Fires before every call to the model, so it is the start of the wait. */
+	providerRequestSent(): void {
+		this.#sentAt = this.#now();
+		this.#headersAt = undefined;
+		this.#attach();
+	}
+
+	/** Fires when the response arrives, before its stream is read. */
+	providerResponseArrived(): void {
+		this.#headersAt = this.#now();
+		this.#attach();
+	}
+
 	requestStarted(): void {
-		this.#request = {
-			startedAt: this.#now(),
-			firstTokenAt: undefined,
-			endedAt: undefined,
-			usage: emptyTotals(),
-			characters: 0,
-		};
+		// A turn begins, and nothing has left for it yet.
+		this.#sentAt = undefined;
+		this.#headersAt = undefined;
+		this.#begin();
 		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. */
+	// Later requests of a turn: the model answered, a tool ran, and the next call is already on its way.
 	answerStarted(): void {
-		if (this.#request === undefined || this.#request.endedAt !== undefined) this.requestStarted();
+		if (this.#request === undefined || this.#request.endedAt !== undefined) this.#begin();
 	}
 
-	/** A piece of the answer: text, thinking or a tool call being written. */
-	answerGrew(delta: string, usage: UsageLike): void {
+	answerGrew(delta: string, usage: UsageLike, kind: DeltaKind): 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();
+		if (kind === "writing") request.firstWritingAt ??= 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;
@@ -124,51 +139,31 @@ export class Telemetry {
 		request.usage = usageTotals(usage);
 		if (request.usage.output === 0 && request.firstTokenAt === undefined) return undefined;
 
+		if (request.characters > 0 && request.usage.output > 0) {
+			this.#sampled.characters += request.characters;
+			this.#sampled.output += request.usage.output;
+		}
+
 		const firstTokenAt = request.firstTokenAt ?? now;
-		this.#last = this.request();
+		const from = request.sentAt ?? request.startedAt;
+		this.#last = this.#view(request);
 		return {
 			output: request.usage.output,
 			prompt: promptOf(request.usage),
-			firstTokenMs: firstTokenAt - request.startedAt,
+			firstTokenMs: firstTokenAt - from,
 			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,
-		};
+		return request === undefined ? undefined : this.#view(request);
 	}
 
-	/** 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;
@@ -184,5 +179,63 @@ export class Telemetry {
 		this.#run = undefined;
 		this.#request = undefined;
 		this.#last = undefined;
+		this.#sentAt = undefined;
+		this.#headersAt = undefined;
+	}
+
+	#begin(): void {
+		this.#request = {
+			startedAt: this.#now(),
+			sentAt: this.#sentAt,
+			headersAt: this.#headersAt,
+			firstTokenAt: undefined,
+			firstWritingAt: undefined,
+			endedAt: undefined,
+			usage: emptyTotals(),
+			characters: 0,
+		};
+	}
+
+	/** The marks belong to a request that may not exist yet: pi sends before it opens the message. */
+	#attach(): void {
+		const request = this.#request;
+		if (request === undefined || request.endedAt !== undefined) return;
+		request.sentAt = this.#sentAt;
+		request.headersAt = this.#headersAt;
+	}
+
+	#view(request: Request): RequestView {
+		const now = this.#now();
+		const streaming = request.endedAt === undefined;
+		const from = request.sentAt ?? request.startedAt;
+		const waitMs = span(from, request.firstTokenAt);
+		const estimated = streaming && request.usage.output === 0;
+		const output = estimated
+			? Math.round(request.characters / this.#charsPerToken())
+			: request.usage.output;
+		const writingMs =
+			request.firstTokenAt === undefined ? 0 : (request.endedAt ?? now) - request.firstTokenAt;
+		const thoughtMs = span(request.firstTokenAt, request.firstWritingAt);
+
+		return {
+			streaming,
+			waiting: streaming && request.firstTokenAt === undefined,
+			elapsedMs: (request.endedAt ?? now) - request.startedAt,
+			waitMs,
+			waitingMs: (request.endedAt ?? now) - from,
+			serverMs: span(request.sentAt, request.headersAt),
+			prefillMs: span(request.headersAt ?? request.sentAt, request.firstTokenAt),
+			thoughtMs: thoughtMs !== undefined && thoughtMs > 0 ? thoughtMs : undefined,
+			decode: writingMs < MIN_SAMPLE_MS && streaming ? undefined : perSecond(output, writingMs),
+			prefill: waitMs === undefined ? undefined : perSecond(promptOf(request.usage), waitMs),
+			usage: { ...request.usage, output },
+			estimated,
+		};
+	}
+
+	/** The measured mix of this session, or the one measured over a machine's worth of answers. */
+	#charsPerToken(): number {
+		const { characters, output } = this.#sampled;
+		return output > 0 ? characters / output : DEFAULT_CHARS_PER_TOKEN;
 	}
 }

package/src/data/totals.ts

@@ -1,5 +1,3 @@
-// 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 {
@@ -18,18 +16,10 @@ interface UsageLike {
 	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;
 }
 
@@ -38,9 +28,7 @@ export const REQUEST_ENTRY = "pi-look:request";
 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;
 }
 
@@ -62,7 +50,6 @@ export function usageTotals(usage: UsageLike): Totals {
 	return totals;
 }
 
-/** The whole branch, not just the messages after the last compaction. */
 export function totalsOf(entries: readonly SessionEntry[]): Totals {
 	const totals = emptyTotals();
 
@@ -79,7 +66,6 @@ export function totalsOf(entries: readonly SessionEntry[]): Totals {
 	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];

package/src/desktop/palette.ts

@@ -1,21 +1,12 @@
-// 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>>;
 }
 
@@ -29,7 +20,6 @@ export interface ThemeJson {
 
 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");
@@ -49,7 +39,6 @@ export function parseDesktopColors(json: unknown, mode?: Mode): DesktopColors |
 	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",
@@ -157,8 +146,6 @@ export function desktopTheme(colors: DesktopColors): ThemeJson {
 		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",
@@ -189,7 +176,6 @@ type BackgroundToken =
 	| "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);

package/src/desktop/sync.ts

@@ -1,5 +1,3 @@
-// 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";
@@ -9,7 +7,6 @@ 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 =
@@ -26,7 +23,6 @@ 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 {
@@ -57,10 +53,7 @@ export async function syncDesktopTheme(source: string): Promise<SyncResult> {
 	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.
- */
+/** Watches the folder: an atomic write replaces 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;