@adeildo/pi-look 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adeildo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @adeildo/pi-look
+
+[![npm](https://img.shields.io/npm/v/@adeildo/pi-look)](https://www.npmjs.com/package/@adeildo/pi-look)
+
+[Pi](https://pi.dev)'s start screen, editor, footer and working line, redrawn around the data that matters while the agent works, and painted only with the colours of the theme that is on.
+
+```bash
+pi install npm:@adeildo/pi-look
+```
+
+It also comes in [`@adeildo/pi-harness`](../harness), with the rest of the pieces.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/preview.png" alt="The start card with the model, the folder, the branch and the keys, and below it the framed editor with the branch and folder in its top border and the model and context in its bottom border." width="860">
+</p>
+
+## What is on the screen
+
+**The start card** says what the session starts with: the model and its effort, the folder and the state of the tree, the machine, how many tools, skills, prompts and extensions loaded, and the keys worth knowing, read from your keybindings. The π is coloured along the theme's effort ramp.
+
+**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 |
+
+The live pieces, which move with every token, go in any slot too: `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 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 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.
+
+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.
+
+## Colours
+
+The look never names a colour. Every piece names a **theme token**, so it follows whatever theme pi runs: `system`, `dark`, `light`, a JSON of yours, or the desktop theme below. Change the theme and every piece moves with it.
+
+| What                                          | Token                                                       |
+| --------------------------------------------- | ----------------------------------------------------------- |
+| Folder                                        | `accent`                                                    |
+| Branch                                        | `syntaxFunction`                                            |
+| Ahead, staged / behind, modified / conflicted | `success` / `warning` / `error`                             |
+| Machine, cache                                | `syntaxType`                                                |
+| Session name                                  | `mdHeading`                                                 |
+| Provider, model icon                          | `syntaxKeyword`                                             |
+| Model                                         | `text`, bold                                                |
+| Sent `↑`                                      | `mdLink`                                                    |
+| Received `↓`, speeds, done                    | `success`                                                   |
+| Time to first token, money                    | `syntaxNumber`, then `warning` past $1 and `error` past $10 |
+| Context                                       | `success`, `warning` past 70%, `error` past 90%             |
+| Effort meter, the π                           | `thinkingMinimal` … `thinkingMax`, one per level            |
+| Labels, units, separators                     | `dim`                                                       |
+| Editor frame                                  | pi's effort border colour                                   |
+
+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. The table lives in `src/render/paint.ts` as `ROLE_TOKENS`, and a test fails if any entry is ever a colour instead of a token.
+
+### The desktop theme
+
+If you run [DankMaterialShell](https://github.com/AvengeMedia/DankMaterialShell), matugen already made a palette from your wallpaper: the Material roles for dark and light, and sixteen terminal colours, in `~/.cache/DankMaterialShell/dms-colors.json`. The look turns that file into the pi theme `desktop`, writes it to `~/.pi/agent/themes/desktop.json`, and rewrites it whenever the file changes. Pi reloads the active theme from that folder by itself, so a new wallpaper recolours a running pi.
+
+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
+```
+
+The mapping, from the Material roles and the terminal colours:
+
+| Pi                                 | Desktop                                                                                             |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `accent`, links, keywords, bullets | `primary`                                                                                           |
+| `text`, `muted`, `dim`             | `on_surface`, `on_surface_variant`, `outline`                                                       |
+| borders                            | `outline`, `primary`, `outline_variant`                                                             |
+| selection, messages, pending tools | the `surface_container` steps                                                                       |
+| `success`, `warning`, `error`      | terminal green, terminal yellow, `error`                                                            |
+| tool success and error backgrounds | a surface mixed with green or with `error`                                                          |
+| headings, functions, custom labels | `tertiary`                                                                                          |
+| code, types                        | `secondary`, terminal cyan                                                                          |
+| effort ramp, off to max            | `outline_variant`, `outline`, `secondary`, `primary`, `tertiary`, terminal bright red, terminal red |
+
+Material has no success, warning or diff roles, so the terminal colours of that hue stand in. The top of the effort ramp uses the terminal reds on purpose: they keep their meaning whatever the wallpaper, so the frame still reads hot at `xhigh` and `max`.
+
+Another palette source is a new file next to `src/desktop/palette.ts`: a parser into Material roles and terminal colours, and the same mapping does the rest.
+
+## Settings
+
+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                                                                                                                                             |
+
+### Segments
+
+Any segment goes in any slot, in the order the slot lists them.
+
+| Id             | Shows                                                                                                 |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| `path`         | The working folder, with home as `~`                                                                  |
+| `branch`       | The branch, ahead `↑` and behind `↓`, staged `+`, modified `~`, untracked `?`, conflicts `!`, stashes |
+| `host`         | The machine, so a pasted line says where it came from                                                 |
+| `session`      | The session name, once it has one                                                                     |
+| `version`      | The pi version                                                                                        |
+| `clock`        | The time                                                                                              |
+| `model`        | `provider/model`                                                                                      |
+| `provider`     | The provider on its own                                                                               |
+| `effort`       | The effort meter and level. Hidden for models that do not reason                                      |
+| `context`      | Context used, the gauge, tokens over the window                                                       |
+| `speed`        | This answer's speeds, received `↓` and sent `↑`                                                       |
+| `wait`         | Time to the first token                                                                               |
+| `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                                    |
+| `request`      | This answer's tokens, with the cache                                                                  |
+| `costRate`     | This answer's cost per million tokens                                                                 |
+| `cost`         | The session's cost                                                                                    |
+| `tokens`       | The session's tokens, with the cache                                                                  |
+| `cache`        | The cache hit of the last prompt                                                                      |
+| `average`      | The session's average speeds, both ways                                                               |
+| `statuses`     | What other packages report through `setStatus`, minus the ones placed on their own                    |
+| `status:<key>` | One package's status, by the key it passes to `setStatus`                                             |
+
+A `status:<key>` segment is how a package gets a place of its own. [`@adeildo/pi-ask-permission`](../ask-permission) reports its mode as `pi-ask-permission:mode`, and the mode says what happens to what you type, so by default it sits in the frame next to the model instead of in the footer with everything else.
+
+## How it fits
+
+When a line runs out of room, the least important pieces take their short form first (the folder becomes its last part, the model loses its provider, the effort meter loses its label), and then leave, one at a time. The two sides of a border compete for the same width, so an unimportant piece on the right leaves before an important one on the left. A line never goes empty: the last piece stays and is cut.
+
+The frame is the editor pi already has. Typing, history, autocomplete and every app key stay pi's; the class only changes what the lines look like and shifts mouse clicks by the width of the frame. The spinner is pi's, embedded through pi's own hook, and the working line only speaks through `setWorkingMessage`.
+
+## Credit
+
+The framed editor and the idea of writing into its borders come from [pi-open-tui](https://github.com/OldSuns/pi-open-tui), which this replaces. The segments with priorities, and the status line in the editor border, come from [oh-my-pi](https://github.com/can1357/oh-my-pi).
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@adeildo/pi-look",
+	"version": "4.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",
+		"pi-coding-agent",
+		"pi-extension",
+		"pi-package",
+		"statusline",
+		"theme",
+		"tui"
+	],
+	"homepage": "https://github.com/felipeadeildo/pi-harness/tree/main/packages/look#readme",
+	"bugs": "https://github.com/felipeadeildo/pi-harness/issues",
+	"license": "MIT",
+	"author": {
+		"name": "adeildo",
+		"email": "contato@felipeadeildo.com",
+		"url": "https://github.com/felipeadeildo"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/felipeadeildo/pi-harness.git",
+		"directory": "packages/look"
+	},
+	"files": [
+		"src",
+		"assets/preview.png",
+		"README.md",
+		"LICENSE"
+	],
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@adeildo/pi-kit": "4.0.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./src/index.ts"
+		],
+		"image": "https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/preview.png"
+	}
+}

package/src/data/git.ts

@@ -0,0 +1,58 @@
+// 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;
+	stashed: number;
+}
+
+export function emptyGit(): GitState {
+	return { ahead: 0, behind: 0, staged: 0, modified: 0, untracked: 0, conflicted: 0, stashed: 0 };
+}
+
+export function parseStatus(output: string): GitState {
+	const state = emptyGit();
+
+	for (const line of output.split("\n")) {
+		if (line.startsWith("# branch.ab ")) {
+			const [, , ahead, behind] = line.split(" ");
+			state.ahead = Math.abs(Number(ahead ?? "0")) || 0;
+			state.behind = Math.abs(Number(behind ?? "0")) || 0;
+		} else if (line.startsWith("# stash ")) {
+			state.stashed = Number(line.slice("# stash ".length)) || 0;
+		} else if (line.startsWith("1 ") || line.startsWith("2 ")) {
+			// `XY` is the index column, then the tree column, with `.` for unchanged.
+			const index = line[2];
+			const tree = line[3];
+			if (index !== undefined && index !== ".") state.staged++;
+			if (tree !== undefined && tree !== ".") state.modified++;
+		} else if (line.startsWith("u ")) {
+			state.conflicted++;
+		} else if (line.startsWith("? ")) {
+			state.untracked++;
+		}
+	}
+
+	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(
+			"git",
+			["-C", cwd, "status", "--porcelain=v2", "--branch", "--show-stash"],
+			{ timeout: 2000 },
+			(error, stdout) => resolve(error === null ? parseStatus(stdout) : undefined),
+		);
+	});
+}

package/src/data/snapshot.ts

@@ -0,0 +1,173 @@
+// 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";
+
+import type { GitState } from "./git.ts";
+import type { RequestView, RunView } from "./telemetry.ts";
+import {
+	type Averages,
+	averagesOf,
+	cacheHitPercent,
+	cacheWarming,
+	emptyTotals,
+	type Totals,
+	totalsOf,
+} from "./totals.ts";
+
+export interface ModelInfo {
+	name: string;
+	/** As the provider wants to be written, not the id pi routes by. */
+	provider: string;
+	reasoning: boolean;
+}
+
+export interface ContextInfo {
+	percent: number;
+	tokens: number;
+	window: number;
+}
+
+export interface Snapshot {
+	now: number;
+	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;
+	version: string;
+	model: ModelInfo | undefined;
+	thinking: string | undefined;
+	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>;
+}
+
+export function emptySnapshot(): Snapshot {
+	return {
+		now: 0,
+		cwd: "",
+		home: undefined,
+		branch: null,
+		git: undefined,
+		host: undefined,
+		sessionName: undefined,
+		version: VERSION,
+		model: undefined,
+		thinking: undefined,
+		context: undefined,
+		totals: emptyTotals(),
+		cacheHit: undefined,
+		cacheWarming: false,
+		subscription: false,
+		request: undefined,
+		last: undefined,
+		run: undefined,
+		averages: { decode: undefined, prefill: undefined },
+		statuses: new Map(),
+	};
+}
+
+export interface LiveInputs {
+	branch: string | null;
+	git: GitState | undefined;
+	request: RequestView | undefined;
+	last: RequestView | undefined;
+	run: RunView | undefined;
+	statuses: ReadonlyMap<string, string>;
+}
+
+interface Derived {
+	totals: Totals;
+	cacheHit: number | undefined;
+	cacheWarming: boolean;
+	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;
+	readonly #host = hostname().split(".")[0];
+
+	read(ctx: ExtensionContext, live: LiveInputs): Snapshot {
+		const model = ctx.model;
+		const derived = this.#derive(ctx);
+
+		return {
+			now: Date.now(),
+			cwd: ctx.cwd,
+			home: process.env.HOME ?? process.env.USERPROFILE,
+			branch: live.branch,
+			git: live.git,
+			host: this.#host,
+			sessionName: ctx.sessionManager.getSessionName(),
+			version: VERSION,
+			model:
+				model === undefined
+					? undefined
+					: {
+							name: model.name ?? model.id,
+							provider: ctx.modelRegistry.getProviderDisplayName(model.provider),
+							reasoning: model.reasoning,
+						},
+			thinking: ctx.thinkingLevel,
+			context: contextOf(ctx),
+			...derived,
+			subscription: model === undefined ? false : ctx.modelRegistry.isUsingOAuth(model),
+			request: live.request,
+			last: live.last,
+			run: live.run,
+			statuses: new Map(
+				[...live.statuses.entries()]
+					.toSorted(([a], [b]) => a.localeCompare(b))
+					.map(([key, text]): [string, string] => [key, sanitize(text)])
+					.filter(([, text]) => text !== ""),
+			),
+		};
+	}
+
+	#derive(ctx: ExtensionContext): Derived {
+		// Every entry is appended at the leaf, so the leaf moving is the only way the sums change.
+		const key = ctx.sessionManager.getLeafId() ?? "";
+		if (this.#derived !== undefined && key === this.#key) return this.#derived;
+
+		const entries: readonly SessionEntry[] = ctx.sessionManager.getBranch();
+		this.#key = key;
+		this.#derived = {
+			totals: totalsOf(entries),
+			cacheHit: cacheHitPercent(entries),
+			cacheWarming: cacheWarming(entries),
+			averages: averagesOf(entries),
+		};
+		return this.#derived;
+	}
+}
+
+function contextOf(ctx: ExtensionContext): ContextInfo | undefined {
+	const usage = ctx.getContextUsage();
+	if (usage === undefined || usage.percent === null || usage.tokens === null) return 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

@@ -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;
+	}
+}