@adeildo/pi-look 5.14.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,89 +5,99 @@
5
5
  <a href="https://pi.dev"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Ffelipeadeildo%2Fpi-harness%2Fmain%2Fpackage.json&query=%24.devDependencies%5B%22%40earendil-works%2Fpi-coding-agent%22%5D&label=pi%20SDK&color=6E56CF" alt="pi SDK"></a>
6
6
  </p>
7
7
 
8
- <p align="center">
9
- <strong>Pi's screen, drawn around the numbers that matter while the agent works.</strong><br>
10
- The start card, the editor framed with the branch and the model, a box around every command, and a footer with what the session costs.
11
- </p>
8
+ While an agent works, you keep checking the same few things: what it is about to run, whether that went well, how long it has been, and what it costs. This package redraws pi's screen around those things. You get a start card, an editor framed with the branch and the model, a box around every command, and a footer with what the session costs.
12
9
 
13
10
  <p align="center"><code>pi install npm:@adeildo/pi-look</code></p>
14
11
 
15
12
  <!-- docs:look/preview -->
16
13
 
17
14
  <p align="center">
18
- <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/preview.png" alt="Pi with the look: the start card, then the strip with the stopwatch and the last call, the task under way with how many wait, are queued and are done, the framed editor with the branch, the model and the context, and below it the cost, the tokens, the cache and the average speeds." width="860">
15
+ <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/preview.png" alt="Pi with the look: the start card, then the strip with the stopwatch and the last call, the card under way with how many wait, are to do and are done, the framed editor with the branch, the model and the context, and below it the cost, the tokens, the cache and the average speeds." width="860">
19
16
  <br>
20
17
  <em>The start card, then a prompt halfway through its answer.</em>
21
18
  </p>
22
19
 
23
20
  <!-- /docs -->
24
21
 
22
+ ## The start card
23
+
24
+ The card shows the π, the folder, the branch, the model, and the name that the rooms and the remote page use for this session. Under them, it lists only what changed or waits on you since your last session in the folder:
25
+
26
+ - an account that needs you to sign in again
27
+ - files in conflict, or a branch behind its remote
28
+ - a failed CI run on the branch
29
+ - a pull request of yours with changes requested or a new comment
30
+ - other agents working in the folder
31
+ - a plan past 70% of its limit
32
+ - a new version of the harness
33
+
34
+ On a quiet day, the card says that nothing is new. GitHub is asked in the background, so the card never waits for it. Without `gh`, without a network, or outside GitHub, those lines just stay out.
35
+
36
+ ## Each command in a box
37
+
38
+ Every command gets its own box, so you see it before it runs: the command, who let it run and why, what it printed, and how long it took. For an edit, the box shows the diff, and only the words that changed get a light background.
39
+
25
40
  <!-- docs:look/call -->
26
41
 
27
42
  <p align="center">
28
- <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/call.png" alt="Three commands, each in its own box: a bash command with the reason it was allowed and the time it took, a file read, and a command still running." width="420">
29
- <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/settings.png" alt="The settings screen in a frame, titled Settings. The Look tab holds Appearance, Your messages and What is on screen, with Editor frame selected. Under the list, the preview draws the editor's rounded frame with main on the top edge, the folder on the right, the model on the bottom edge and the context on the right. Below, the setting's name and default, and the keys along the bottom edge." width="420">
43
+ <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/call.png" alt="Three commands, each in its own box: a bash command with the reason it was allowed and the time it took, a file read, and a command still running." width="860">
30
44
  <br>
31
- <em>Every command in a box, and a setting shown before you keep it.</em>
45
+ <em>Every command in its own box: what ran, who let it run, the output and the time.</em>
32
46
  </p>
33
47
 
34
48
  <!-- /docs -->
35
49
 
36
- ## The screen
37
-
38
- A finished answer takes a box of its own, so you can see what the model wants to run before it runs. The mark of the tool and its name sit on the top line, the command under them, and the reason it was allowed under that, when another model answered it. A line cuts the command off from what it printed, and the bottom line says how it went: a check, a cross, and how long it took. A command still running says `running` with the time so far. A tool from an MCP server shows its server and tool instead of `mcp__server__tool`. A tool with no drawing of its own, like the memory calls, gets the same box with its name and arguments on top and its text under the cut.
39
-
40
- The strip above the editor is calm on purpose. Nothing moves while the model streams except the stopwatch.
50
+ `Alt+O` opens the tool output of the session, one call at a time. `Ctrl+O` opens every call in the transcript.
41
51
 
42
- | Piece | Means |
43
- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
44
- | `0:12 3 calls` | How long the agent has worked on this prompt, and how many calls to the model it made |
45
- | `last call 1.7s wait 900ms thought ↓906 tok/s` | The last call: how long the model took to start, how long it thought then wrote, and how fast it writes |
46
- | `answered in 0:47 2 calls $0.31` | Once the run ends: how long it took, how many calls to the model, and what it cost |
52
+ ## Above the editor
47
53
 
48
- The border around the editor carries the branch with its distance and changes, the folder, the permission mode, the model with an effort meter, and the context. It takes pi's own effort colour, so it warms up as the model thinks harder and turns to the shell colour in bash mode.
54
+ The strip above the editor stays calm. While the model streams, only the stopwatch moves.
49
55
 
50
- 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.
56
+ | What you see | What it means |
57
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
58
+ | `0:12 3 calls` | How long the agent has worked on this prompt, and how many calls it made to the model |
59
+ | `last call 1.7s wait 900ms thought ↓906 tok/s` | How long the last call took to start, to think and write, and how fast it wrote |
60
+ | `answered in 0:47 2 calls $0.31` | Once the run ends: how long it took, how many calls, and what it cost |
51
61
 
52
- Your messages sit in a frame like the tool calls', in the accent colour and named `you`, without pi's background or the blank rows above and below the text. `look.userFrame` turns it off.
62
+ On the right, the strip shows the card the agent is working on, and the rooms this session is in:
53
63
 
54
- The start card shows the π, the folder, the branch and the model, and under them only what changed or waits on you since your last session in the folder: an account that needs a sign-in, files in conflict, a branch behind its remote, a failed CI run on the branch, a pull request of yours with changes requested or a new comment, other agents working there, a plan past 70%, a new harness version. On a quiet day it says nothing is new, and its bottom edge reads `ready when you are`. GitHub is asked once per launch, in the background, so the card never waits on it: those two lines appear when the answers arrive, and a missing `gh`, no network or a folder that is not on GitHub leaves them out. The π rises from its feet once per launch. With pi's `quietStartup` on `header`, which the harness sets, pi's list of everything it loaded stays out of the way.
64
+ - Each room shows how this session stands there: `●` takes part, `◐` listens, `○` stepped out.
65
+ - After the room come its agents, each with what it is doing: `◆` working, `⚑` waiting on you, `◇` idle.
55
66
 
56
- The mark of a phase that lasts moves: a clock goes round its hours while a call runs, the hourglass flows while it waits on you, and a braille spinner turns while the model writes the call, in its own cell. With the Unicode icons a quarter circle goes round while the call runs, and with ASCII a line spins. The mark stands still once the call ends.
67
+ The messages that you send while the agent works wait above the editor, in a dashed frame. `steer` means the message goes in between the agent's calls, and `next` means it goes after the run.
57
68
 
58
- Pi's own entries sit in the same frame as the tool calls: compactions and branch summaries under `π`, skills, `!` commands with a cut between the command and what it printed, and the messages of extensions that bring no renderer of their own. The messages you send while the agent works wait above the editor in a dashed frame, each marked `steer` (between the agent's calls) or `next` (after its run), with the key that takes them back to the editor in the bottom edge.
69
+ ## The editor and the footer
59
70
 
60
- While the model writes an `edit` or a `write`, its frame shows the end of what has arrived, with a cursor where the model is writing. A write shows its last 8 lines with their numbers, and says whether it makes a new file or how many lines it replaces. An edit shows the lines it takes out and puts in. The lines it repeats around the change stay as context. The bottom rule counts the lines and the size, or the edits and the lines changed. Once the call is written, pi's own view takes over, with the diff read from the file.
71
+ The editor's border shows this session's name, the branch, the folder, the permission mode, the model and how full the context is. The footer shows what the session cost, the tokens, the cache, the speeds, and how much of your plan is left.
61
72
 
62
- The footer is the session, each number with its word: the cost, the tokens sent and received, how much of the last prompt was cached, the average speeds, the plan's windows with when they reset, and last what other packages report, because that changes the most.
73
+ Nothing on the screen jumps around: every number has a fixed width, and a value that nobody knows yet shows as `–` instead of popping in later.
63
74
 
64
- `Alt+O` opens the session's tool output in a frame you scroll, one call at a time, newest first. The arrows up and down scroll it, left and right move to older and newer calls, and the bottom edge says which lines you are on. Pi shows a long output cut in the transcript, and `Ctrl+O` opens every call at once.
65
-
66
- ## It holds still
67
-
68
- Numbers change on every frame, and the screen must not move with them.
75
+ ## Settings
69
76
 
70
- - Every number sits in a cell of fixed width, so ` 17` and `2.8k` take the same room.
71
- - A value nobody knows yet shows as `–` and does not appear later in the middle of the line.
72
- - The working time counts as a stopwatch, `0:59` then `1:00`.
73
- - An estimate is drawn quieter, so you know it is one.
74
- - The strip and the footer hold their line from the start, so the editor does not jump when the first answer arrives.
77
+ `Alt+S` opens them on the Look tab. You choose the icons (Nerd Font, Unicode or ASCII, to match your terminal's font), the style of the editor's frame, and whether your messages sit in a frame. Each choice shows a preview before you keep it.
75
78
 
76
- Pi records usage without a duration, so every finished answer leaves one small entry in the session with its time to the first token and its writing time. That is what keeps the averages right after a resume.
79
+ <!-- docs:look/settings -->
77
80
 
78
- ## Your theme
81
+ <p align="center">
82
+ <img src="https://raw.githubusercontent.com/felipeadeildo/pi-harness/main/packages/look/assets/settings.png" alt="The settings screen in a frame, titled Settings. The Look tab holds Appearance, Your messages and What is on screen, with Editor frame selected. Under the list, the preview draws the editor's rounded frame with main on the top edge, the folder on the right, the model on the bottom edge and the context on the right. Below, the setting's name and default, and the keys along the bottom edge." width="860">
83
+ <br>
84
+ <em>Change a setting and see the result drawn under the list before you keep it.</em>
85
+ </p>
79
86
 
80
- The look never names a colour. Every piece names a theme token, so it follows whatever theme pi runs, and it moves with it when you change themes. The [reference](docs/reference.md#colours) maps each piece to its token.
87
+ <!-- /docs -->
81
88
 
82
- ## Settings
89
+ ## Learn more
83
90
 
84
- `Alt+S` opens them on the Look tab. The look is opinionated, so three things are yours: the icons (Nerd Font, Unicode or ASCII, which depend on your terminal's font), the style of the editor's frame, and whether your messages sit in a frame. Each shows a preview of what it changes as you pick it. The [reference](docs/reference.md#settings) lists them.
91
+ - [How it works](docs/how-it-works.md): the strip and the footer in detail, another session over the screen, and how the screen holds still.
92
+ - [Reference](docs/reference.md): every setting and the theme token behind each color.
85
93
 
86
- 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 come from [oh-my-pi](https://github.com/can1357/oh-my-pi).
94
+ The framed editor comes from [pi-open-tui](https://github.com/OldSuns/pi-open-tui), which this package replaces. The segments with priorities come from [oh-my-pi](https://github.com/can1357/oh-my-pi).
87
95
 
88
- Part of [pi-harness](https://github.com/felipeadeildo/pi-harness), which brings every piece in one install.
96
+ <!-- docs:footer -->
89
97
 
90
98
  <p align="center">
91
99
  <a href="https://adeildo.dev"><img src="https://adeildo.dev/assets/images/cat.svg" width="42" height="42" alt="adeildo.dev"></a><br>
92
- Brought to you by <a href="https://adeildo.dev">adeildo.dev</a>
100
+ <a href="https://github.com/felipeadeildo/pi-harness">pi-harness</a> is made by <a href="https://adeildo.dev">adeildo.dev</a>
93
101
  </p>
102
+
103
+ <!-- /docs -->
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adeildo/pi-look",
3
- "version": "5.14.0",
3
+ "version": "6.0.0",
4
4
  "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.",
5
5
  "keywords": [
6
6
  "pi",
@@ -38,7 +38,8 @@
38
38
  "access": "public"
39
39
  },
40
40
  "dependencies": {
41
- "@adeildo/pi-kit": "5.14.0"
41
+ "@adeildo/pi-kit": "6.0.0",
42
+ "diff": "8.0.4"
42
43
  },
43
44
  "peerDependencies": {
44
45
  "@earendil-works/pi-ai": "*",
package/src/data/git.ts CHANGED
@@ -49,7 +49,7 @@ export async function readGit(
49
49
  await run("git", ["-C", cwd, "status", "--porcelain=v2", "--branch", "--show-stash"]),
50
50
  );
51
51
  } catch {
52
- // A folder that is not a repository, or a git that did not answer: the card says nothing.
52
+ // Not a repository, or git did not answer: the card says nothing.
53
53
  return undefined;
54
54
  }
55
55
  }
@@ -1,27 +1,22 @@
1
- // The answers GitHub gives the start card: the last run of CI on this branch, and your own open pull
2
- // requests with something waiting on you. The card asks once per launch, in the background, and shows
3
- // nothing when gh is missing, the network is down, or the folder is not on GitHub.
1
+ // CI's last run on this branch and your open pull requests that wait on you, asked once per launch.
2
+ // Shows nothing without gh, network or a GitHub remote.
4
3
  import { isObject } from "@adeildo/pi-kit";
5
4
 
6
5
  import { processRunner, type Runner } from "./runner.ts";
7
6
 
8
- /** The conclusions that mean a run did not pass. */
9
7
  const FAILED = new Set(["failure", "startup_failure", "timed_out"]);
10
- /** What gh is asked about a pull request: enough to tell a new comment from an old one. */
8
+ /** Enough to tell a new comment from an old one. */
11
9
  const PR_FIELDS = "number,title,author,reviewDecision,comments";
12
10
 
13
- export interface CiFailure {
11
+ interface CiFailure {
14
12
  branch: string;
15
- /** The failing commit, short enough to read. */
16
13
  sha: string;
17
- /** The workflow that failed. */
18
14
  name: string;
19
15
  }
20
16
 
21
- export interface OpenPullRequest {
17
+ interface OpenPullRequest {
22
18
  number: number;
23
19
  title: string;
24
- /** What waits on you there. */
25
20
  waits: "changes requested" | "new comment";
26
21
  }
27
22
 
@@ -30,10 +25,7 @@ export interface GithubState {
30
25
  pr: OpenPullRequest | undefined;
31
26
  }
32
27
 
33
- /**
34
- * What GitHub knows about this folder. It never rejects: every question that cannot be answered
35
- * leaves its note out. `since` is the last session in the folder, the bar for a comment to be news.
36
- */
28
+ /** Never rejects. `since` is the last session here, the bar for a comment to be news. */
37
29
  export async function readGithub(
38
30
  cwd: string,
39
31
  since: number | undefined,
@@ -49,7 +41,6 @@ async function branchOf(run: Runner): Promise<string | undefined> {
49
41
  return branch === undefined || branch === "" ? undefined : branch;
50
42
  }
51
43
 
52
- /** The last run of CI on the branch, when it failed. */
53
44
  async function failedRun(run: Runner, branch: string): Promise<CiFailure | undefined> {
54
45
  const out = await ask(() =>
55
46
  run("gh", [
@@ -74,7 +65,6 @@ async function failedRun(run: Runner, branch: string): Promise<CiFailure | undef
74
65
  };
75
66
  }
76
67
 
77
- /** The first of your open pull requests, newest first, with a review or a comment waiting on you. */
78
68
  async function pullRequest(
79
69
  run: Runner,
80
70
  since: number | undefined,
@@ -110,7 +100,6 @@ function loginOf(value: unknown): string | undefined {
110
100
  return isObject(value) ? field(value, "login") : undefined;
111
101
  }
112
102
 
113
- /** The stdout of a question that could not be asked is no answer at all. */
114
103
  async function ask(question: () => Promise<string>): Promise<string | undefined> {
115
104
  try {
116
105
  return await question();
@@ -1,12 +1,11 @@
1
1
  import { execFile } from "node:child_process";
2
2
 
3
- /** How long one command may take before it is given up on. The start card is never worth a longer wait. */
3
+ /** The start card is never worth a longer wait. */
4
4
  const TIMEOUT_MS = 3000;
5
- /** Room for a page of an answer, like your open pull requests with their comments. Node's own
6
- * default, so a command that answered before keeps answering. */
5
+ /** Room for a page of answers, like your open pull requests with their comments. */
7
6
  const MAX_OUTPUT = 1024 * 1024;
8
7
 
9
- /** Runs one command in the folder and returns its stdout. Rejects when it fails or takes too long. */
8
+ /** Rejects when it fails or takes too long. */
10
9
  export type Runner = (file: string, args: readonly string[]) => Promise<string>;
11
10
 
12
11
  export function processRunner(cwd: string, timeoutMs: number = TIMEOUT_MS): Runner {
@@ -1,6 +1,6 @@
1
1
  import { hostname } from "node:os";
2
2
 
3
- import type { AccountState, PeerMark, SessionTasks } from "@adeildo/pi-kit";
3
+ import type { AccountState, Board, PeerMark, RoomMark, WritingMark } from "@adeildo/pi-kit";
4
4
  import { VERSION, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
5
5
 
6
6
  import type { GitState } from "./git.ts";
@@ -15,13 +15,13 @@ import {
15
15
  totalsOf,
16
16
  } from "./totals.ts";
17
17
 
18
- export interface ModelInfo {
18
+ interface ModelInfo {
19
19
  name: string;
20
20
  provider: string;
21
21
  reasoning: boolean;
22
22
  }
23
23
 
24
- export interface ContextInfo {
24
+ interface ContextInfo {
25
25
  percent: number;
26
26
  tokens: number;
27
27
  window: number;
@@ -35,6 +35,8 @@ export interface Snapshot {
35
35
  git: GitState | undefined;
36
36
  host: string | undefined;
37
37
  sessionName: string | undefined;
38
+ /** The word the room calls this session by, in its color once it is in a room. */
39
+ me: { handle: string; color?: string } | undefined;
38
40
  version: string;
39
41
  model: ModelInfo | undefined;
40
42
  account: AccountState | undefined;
@@ -49,12 +51,14 @@ export interface Snapshot {
49
51
  run: RunView | undefined;
50
52
  averages: Averages;
51
53
  statuses: ReadonlyMap<string, string>;
52
- /** What the session is doing, when a tasks feature keeps it. */
53
- tasks: SessionTasks | undefined;
54
- /** The other sessions in this folder, when a peers feature keeps them. */
54
+ /** When a board feature keeps it. */
55
+ board: Board | undefined;
56
+ /** When a peers feature keeps them. */
55
57
  peers: PeerMark[];
56
- /** Messages a peer sent this session that its agent has not read yet. */
58
+ /** Empty when the peers feature publishes only `peers`. */
59
+ peersRooms: RoomMark[];
57
60
  peersUnread: number;
61
+ peersWriting: WritingMark[];
58
62
  }
59
63
 
60
64
  export function emptySnapshot(): Snapshot {
@@ -66,6 +70,7 @@ export function emptySnapshot(): Snapshot {
66
70
  git: undefined,
67
71
  host: undefined,
68
72
  sessionName: undefined,
73
+ me: undefined,
69
74
  version: VERSION,
70
75
  model: undefined,
71
76
  account: undefined,
@@ -80,9 +85,11 @@ export function emptySnapshot(): Snapshot {
80
85
  run: undefined,
81
86
  averages: { decode: undefined, prefill: undefined },
82
87
  statuses: new Map(),
83
- tasks: undefined,
88
+ board: undefined,
84
89
  peers: [],
90
+ peersRooms: [],
85
91
  peersUnread: 0,
92
+ peersWriting: [],
86
93
  };
87
94
  }
88
95
 
@@ -94,9 +101,12 @@ export interface LiveInputs {
94
101
  last: RequestView | undefined;
95
102
  run: RunView | undefined;
96
103
  statuses: ReadonlyMap<string, string>;
97
- tasks?: SessionTasks | undefined;
104
+ board?: Board | undefined;
105
+ me?: { handle: string; color?: string } | undefined;
98
106
  peers?: PeerMark[] | undefined;
107
+ peersRooms?: RoomMark[] | undefined;
99
108
  peersUnread?: number | undefined;
109
+ peersWriting?: WritingMark[] | undefined;
100
110
  }
101
111
 
102
112
  interface Derived {
@@ -124,6 +134,7 @@ export class SnapshotReader {
124
134
  git: live.git,
125
135
  host: this.#host,
126
136
  sessionName: ctx.sessionManager.getSessionName(),
137
+ me: live.me,
127
138
  version: VERSION,
128
139
  model:
129
140
  model === undefined
@@ -146,16 +157,16 @@ export class SnapshotReader {
146
157
  .map(([key, text]): [string, string] => [key, sanitize(text)])
147
158
  .filter(([, text]) => text !== ""),
148
159
  ),
149
- tasks: live.tasks,
160
+ board: live.board,
150
161
  peers: live.peers ?? [],
162
+ peersRooms: live.peersRooms ?? [],
151
163
  peersUnread: live.peersUnread ?? 0,
164
+ peersWriting: live.peersWriting ?? [],
152
165
  };
153
166
  }
154
167
 
155
168
  #derive(ctx: ExtensionContext): Derived {
156
- // Every entry is appended at the leaf, so the leaf moving is the only way the sums change. The
157
- // context also depends on the model's window. Pi counts it over the whole branch, which is too
158
- // slow to do on every keystroke.
169
+ // Entries are appended at the leaf, so the sums change only when the leaf or the model does.
159
170
  const key = `${ctx.sessionManager.getLeafId() ?? ""}\u0000${ctx.model?.provider}/${ctx.model?.id}`;
160
171
  if (this.#derived !== undefined && key === this.#key) return this.#derived;
161
172
 
@@ -1,14 +1,11 @@
1
- // What the start screen says under the folder and the model: only what changed or waits on you since
2
- // the last session here. On a quiet day the list is empty and the screen says so in one line.
1
+ // Under the folder and the model, only what changed or waits on you since the last session here.
3
2
  import { formatClock, GLYPH } from "@adeildo/pi-kit";
4
3
 
5
4
  import type { GithubState } from "./github.ts";
6
5
  import type { Snapshot } from "./snapshot.ts";
7
6
 
8
- /** Plans used past this percent show on the start screen. */
9
7
  const PLAN_LIMIT = 70;
10
8
 
11
- /** The last session in this folder, as the start screen remembers it. */
12
9
  export interface LastVisit {
13
10
  at: number;
14
11
  version: string;
@@ -16,7 +13,6 @@ export interface LastVisit {
16
13
 
17
14
  export interface StartNote {
18
15
  mark: string;
19
- /** A theme color for the mark. */
20
16
  color: string;
21
17
  text: string;
22
18
  detail?: string;
@@ -98,7 +94,7 @@ function peerState(state: "running" | "idle" | "waiting"): string {
98
94
  }
99
95
  }
100
96
 
101
- /** Local time, hours and minutes, or the day when it was not today. */
97
+ /** Local time, or the day when it was not today. */
102
98
  export function since(at: number, now: number): string {
103
99
  const then = new Date(at);
104
100
  const time = formatClock(at);
@@ -8,25 +8,25 @@ import {
8
8
  } from "./totals.ts";
9
9
 
10
10
  const MIN_SAMPLE_MS = 250;
11
- /** Measured over 16,889 assistant messages of one machine: 2.88 characters per output token. */
11
+ /** Measured over 16,889 assistant messages: 2.88 characters per output token. */
12
12
  const DEFAULT_CHARS_PER_TOKEN = 2.9;
13
13
 
14
- /** What a delta carried, so the wait for the first thought can be told from the first word. */
14
+ /** So the wait for the first thought can be told from the first word. */
15
15
  export type DeltaKind = "thinking" | "writing";
16
16
 
17
17
  export interface RequestView {
18
18
  streaming: boolean;
19
19
  waiting: boolean;
20
20
  elapsedMs: number;
21
- /** From the request leaving to the first token of any kind: what you waited for the model. */
21
+ /** From the request leaving to the first token of any kind. */
22
22
  waitMs: number | undefined;
23
- /** The same wait while it is still running, so the number counts from the moment it left. */
23
+ /** The same wait while it runs. */
24
24
  waitingMs: number;
25
- /** From the request leaving to the response headers: the provider's own latency. */
25
+ /** To the response headers: the provider's own latency. */
26
26
  serverMs: number | undefined;
27
27
  /** From the headers to the first token: the model reading the prompt. */
28
28
  prefillMs: number | undefined;
29
- /** From the first thought to the first word written. Unset when it wrote without thinking. */
29
+ /** Unset when it wrote without thinking. */
30
30
  thoughtMs: number | undefined;
31
31
  decode: number | undefined;
32
32
  prefill: number | undefined;
@@ -38,13 +38,11 @@ export interface RunView {
38
38
  running: boolean;
39
39
  elapsedMs: number;
40
40
  requests: number;
41
- /** What the run's answers cost so far, at the provider's prices. */
42
41
  cost: number;
43
42
  }
44
43
 
45
44
  interface Request {
46
45
  startedAt: number;
47
- /** When the request left, from pi's own `before_provider_request`. */
48
46
  sentAt: number | undefined;
49
47
  headersAt: number | undefined;
50
48
  firstTokenAt: number | undefined;
@@ -78,10 +76,10 @@ export class Telemetry {
78
76
  #run: Run | undefined;
79
77
  #request: Request | undefined;
80
78
  #last: RequestView | undefined;
81
- /** The marks of the request in flight, which arrive before the pi message it belongs to. */
79
+ /** They arrive before the pi message they belong to. */
82
80
  #sentAt: number | undefined;
83
81
  #headersAt: number | undefined;
84
- /** Characters and tokens of the answers that finished, for the live estimate to use a real ratio. */
82
+ /** So the live estimate uses a real ratio. */
85
83
  #sampled = { characters: 0, output: 0 };
86
84
 
87
85
  constructor(now: () => number = Date.now) {
@@ -96,21 +94,20 @@ export class Telemetry {
96
94
  if (this.#run !== undefined && this.#run.endedAt === undefined) this.#run.endedAt = this.#now();
97
95
  }
98
96
 
99
- /** Fires before every call to the model, so it is the start of the wait. */
97
+ /** Before every call to the model: the start of the wait. */
100
98
  providerRequestSent(): void {
101
99
  this.#sentAt = this.#now();
102
100
  this.#headersAt = undefined;
103
101
  this.#attach();
104
102
  }
105
103
 
106
- /** Fires when the response arrives, before its stream is read. */
104
+ /** Before the stream is read. */
107
105
  providerResponseArrived(): void {
108
106
  this.#headersAt = this.#now();
109
107
  this.#attach();
110
108
  }
111
109
 
112
110
  requestStarted(): void {
113
- // A turn begins, and nothing has left for it yet.
114
111
  this.#sentAt = undefined;
115
112
  this.#headersAt = undefined;
116
113
  this.#begin();
@@ -118,7 +115,7 @@ export class Telemetry {
118
115
  if (this.#run !== undefined) this.#run.requests++;
119
116
  }
120
117
 
121
- // Later requests of a turn: the model answered, a tool ran, and the next call is already on its way.
118
+ /** Later requests of a turn: the next call after a tool ran. */
122
119
  answerStarted(): void {
123
120
  if (this.#request === undefined || this.#request.endedAt !== undefined) this.#begin();
124
121
  }
@@ -201,7 +198,7 @@ export class Telemetry {
201
198
  };
202
199
  }
203
200
 
204
- /** The marks belong to a request that may not exist yet: pi sends before it opens the message. */
201
+ /** Pi sends before it opens the message, so the marks may arrive first. */
205
202
  #attach(): void {
206
203
  const request = this.#request;
207
204
  if (request === undefined || request.endedAt !== undefined) return;
@@ -238,7 +235,7 @@ export class Telemetry {
238
235
  };
239
236
  }
240
237
 
241
- /** The measured mix of this session, or the one measured over a machine's worth of answers. */
238
+ /** This session's ratio, or the measured default. */
242
239
  #charsPerToken(): number {
243
240
  const { characters, output } = this.#sampled;
244
241
  return output > 0 ? characters / output : DEFAULT_CHARS_PER_TOKEN;
@@ -1,22 +1,15 @@
1
- import { tasksUsageOf } from "@adeildo/pi-kit";
1
+ import { type UsageLike } from "@adeildo/pi-kit";
2
+
3
+ export {
4
+ emptyTotals,
5
+ promptOf,
6
+ tokensOf,
7
+ totalsOf,
8
+ type Totals,
9
+ usageTotals,
10
+ } from "@adeildo/pi-kit";
2
11
  import type { SessionEntry } from "@earendil-works/pi-coding-agent";
3
12
 
4
- export interface Totals {
5
- input: number;
6
- output: number;
7
- cacheRead: number;
8
- cacheWrite: number;
9
- cost: number;
10
- }
11
-
12
- interface UsageLike {
13
- input: number;
14
- output: number;
15
- cacheRead: number;
16
- cacheWrite: number;
17
- cost: { total: number };
18
- }
19
-
20
13
  export interface RequestRecord {
21
14
  output: number;
22
15
  prompt: number;
@@ -24,51 +17,15 @@ export interface RequestRecord {
24
17
  generationMs: number;
25
18
  }
26
19
 
27
- export const REQUEST_ENTRY = "pi-look:request";
28
- /** Written by this package before it was renamed. It has no `prompt`, so it only counts for decode. */
29
- const LEGACY_ENTRY = "pi-statusline:turn";
20
+ export const REQUEST_CHANGES = "pi-look:request";
21
+ /** Entries from this package's old name. They have no `prompt`, so they count only for decode. */
22
+ const LEGACY_CHANGES = "pi-statusline:turn";
30
23
 
31
24
  export interface Averages {
32
25
  decode: number | undefined;
33
26
  prefill: number | undefined;
34
27
  }
35
28
 
36
- export function emptyTotals(): Totals {
37
- return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
38
- }
39
-
40
- export function promptOf(totals: Totals): number {
41
- return totals.input + totals.cacheRead + totals.cacheWrite;
42
- }
43
-
44
- export function tokensOf(totals: Totals): number {
45
- return promptOf(totals) + totals.output;
46
- }
47
-
48
- export function usageTotals(usage: UsageLike): Totals {
49
- const totals = emptyTotals();
50
- add(totals, usage);
51
- return totals;
52
- }
53
-
54
- export function totalsOf(entries: readonly SessionEntry[]): Totals {
55
- const totals = emptyTotals();
56
-
57
- for (const entry of entries) {
58
- if (entry.type === "usage") add(totals, entry.usage);
59
- else if (entry.type === "message" && entry.message.role === "assistant")
60
- add(totals, entry.message.usage);
61
- else if (entry.type === "message" && entry.message.role === "toolResult" && entry.message.usage)
62
- add(totals, entry.message.usage);
63
- else if ((entry.type === "branch_summary" || entry.type === "compaction") && entry.usage)
64
- add(totals, entry.usage);
65
- else if (entry.type === "custom") addTasks(totals, tasksUsageOf(entry));
66
- }
67
-
68
- return totals;
69
- }
70
-
71
- /** The usage of the last answer the model gave, which is what the cache lines talk about. */
72
29
  function lastAssistantUsage(entries: readonly SessionEntry[]): UsageLike | undefined {
73
30
  for (let index = entries.length - 1; index >= 0; index--) {
74
31
  const entry = entries[index];
@@ -98,7 +55,7 @@ export function averagesOf(entries: readonly SessionEntry[]): Averages {
98
55
 
99
56
  for (const entry of entries) {
100
57
  if (entry.type !== "custom") continue;
101
- if (entry.customType !== REQUEST_ENTRY && entry.customType !== LEGACY_ENTRY) continue;
58
+ if (entry.customType !== REQUEST_CHANGES && entry.customType !== LEGACY_CHANGES) continue;
102
59
  const record = entry.data;
103
60
  if (!isRecord(record)) continue;
104
61
 
@@ -128,19 +85,3 @@ function isRecord(
128
85
  typeof record.generationMs === "number"
129
86
  );
130
87
  }
131
-
132
- // The tasks package's model calls are not pi's, so pi does not count them. They count here.
133
- function addTasks(totals: Totals, usage: ReturnType<typeof tasksUsageOf>): void {
134
- if (usage === undefined) return;
135
- totals.input += usage.input;
136
- totals.output += usage.output;
137
- totals.cost += usage.cost;
138
- }
139
-
140
- function add(totals: Totals, usage: UsageLike): void {
141
- totals.input += usage.input;
142
- totals.output += usage.output;
143
- totals.cacheRead += usage.cacheRead;
144
- totals.cacheWrite += usage.cacheWrite;
145
- totals.cost += usage.cost.total;
146
- }