@adeildo/pi-look 5.0.0 → 5.1.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.
Files changed (2) hide show
  1. package/README.md +22 -119
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@adeildo/pi-look)](https://www.npmjs.com/package/@adeildo/pi-look)
4
4
 
5
- [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.
5
+ [Pi](https://pi.dev)'s start screen, editor, footer and working line, redrawn around the numbers that matter while the agent works. It paints only with the colours of the theme you run, and the screen holds still while the numbers change.
6
6
 
7
7
  ```bash
8
8
  pi install npm:@adeildo/pi-look
@@ -16,141 +16,44 @@ It also comes in [`@adeildo/pi-harness`](../harness), with the rest of the piece
16
16
 
17
17
  ## What is on the screen
18
18
 
19
- **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.
19
+ **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.
20
20
 
21
- **The strip above the editor** is calm on purpose: nothing in it moves while the model streams except the stopwatch.
21
+ **The strip above the editor** is calm on purpose. Nothing in it moves while the model streams except the stopwatch.
22
22
 
23
- | Piece | Means |
24
- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25
- | `0:12 3 calls` | How long the agent has worked on this prompt, and how many calls to the model it made |
26
- | `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 |
23
+ | Piece | Means |
24
+ | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | `0:12 3 calls` | How long the agent has worked on this prompt, and how many calls to the model it made |
26
+ | `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 |
27
27
 
28
- 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`.
28
+ **The frame** 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. The border takes pi's own effort colour, so it warms up as the model thinks harder and turns to the bash colour in shell mode.
29
29
 
30
- 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.
30
+ **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.
31
31
 
32
- **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.
32
+ **The footer** is the session: the cost, tokens sent and received, the cache hit of the last prompt, the average speeds, and last what other packages report, because it changes the most.
33
33
 
34
- **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.
34
+ ## It holds still
35
35
 
36
- **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.
36
+ Numbers change on every frame and the screen must not move with them.
37
37
 
38
- ### It holds still
38
+ - Every number sits in a cell of fixed width, so ` 17` and `2.8k` take the same room.
39
+ - A value not known yet shows as `–` in its cell and does not appear later in the middle of the line.
40
+ - The working time is a stopwatch, `0:59` then `1:00`, instead of `59s` then `1m 0s`.
41
+ - An estimate is drawn quieter and does not gain a `~`.
42
+ - The strip and the footer keep their line from the start, so the editor does not jump when the first answer arrives.
39
43
 
40
- 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.
44
+ 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 keeps the averages right after a resume.
41
45
 
42
- 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.
46
+ ## Your theme, not ours
43
47
 
44
- ## Colours
45
-
46
- 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.
47
-
48
- | What | Token |
49
- | --------------------------------------------- | ----------------------------------------------------------- |
50
- | Folder | `accent` |
51
- | Branch | `syntaxFunction` |
52
- | Ahead, staged / behind, modified / conflicted | `success` / `warning` / `error` |
53
- | Machine, cache | `syntaxType` |
54
- | Session name | `mdHeading` |
55
- | Provider, model icon | `syntaxKeyword` |
56
- | Model | `text`, bold |
57
- | Sent `↑` | `mdLink` |
58
- | Received `↓`, speeds, done | `success` |
59
- | Time to first token, money | `syntaxNumber`, then `warning` past $1 and `error` past $10 |
60
- | Context | `success`, `warning` past 70%, `error` past 90% |
61
- | Effort meter, the π | `thinkingMinimal` … `thinkingMax`, one per level |
62
- | Labels, units, separators | `dim` |
63
- | Editor frame | pi's effort border colour |
64
-
65
- 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.
48
+ 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. The [reference](docs/reference.md#colours) maps each piece to its token.
66
49
 
67
50
  ### The desktop theme
68
51
 
69
- 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.
70
-
71
- 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.
72
-
73
- `Switch to it now`, in the Desktop theme section of the settings (`Alt+S`), writes the theme and makes it pi's.
74
-
75
- The mapping, from the Material roles and the terminal colours:
76
-
77
- | Pi | Desktop |
78
- | ---------------------------------- | --------------------------------------------------------------------------------------------------- |
79
- | `accent`, links, keywords, bullets | `primary` |
80
- | `text`, `muted`, `dim` | `on_surface`, `on_surface_variant`, `outline` |
81
- | borders | `outline`, `primary`, `outline_variant` |
82
- | selection, messages, pending tools | the `surface_container` steps |
83
- | `success`, `warning`, `error` | terminal green, terminal yellow, `error` |
84
- | tool success and error backgrounds | a surface mixed with green or with `error` |
85
- | headings, functions, custom labels | `tertiary` |
86
- | code, types | `secondary`, terminal cyan |
87
- | effort ramp, off to max | `outline_variant`, `outline`, `secondary`, `primary`, `tertiary`, terminal bright red, terminal red |
88
-
89
- 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`.
90
-
91
- 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.
52
+ If you run [DankMaterialShell](https://github.com/AvengeMedia/DankMaterialShell), matugen already made a palette from your wallpaper. The look turns it into the pi theme `desktop`, writes it to `~/.pi/agent/themes/desktop.json` and rewrites it when the palette changes. Pi reloads the active theme from that folder by itself, so a new wallpaper recolours a running pi. `Switch to it now`, in the Desktop theme section of the settings (`Alt+S`), writes the theme and makes it pi's.
92
53
 
93
54
  ## Settings
94
55
 
95
- 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.
96
-
97
- | Key | Default | Does |
98
- | ------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
99
- | `strip` | `["elapsed", "last"]` | The line above the editor. _project_ |
100
- | `frame.topLeft` | `["branch", "session"]` | After the spinner. _project_ |
101
- | `frame.topRight` | `["path", "host"]` | _project_ |
102
- | `frame.bottomLeft` | `["status:pi-ask-permission:mode", "model", "status:pi-providers:account", "effort"]` | _project_ |
103
- | `frame.bottomRight` | `["context"]` | _project_ |
104
- | `below` | `["cost", "tokens", "cache", "average", "statuses"]` | The line below the editor. _project_ |
105
- | `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_ |
106
- | `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_ |
107
- | `frame.cursor` | `"bar"` | `block`, `bar` or `underline`. The last two use the terminal's own cursor |
108
- | `header` | `"card"` | `card`, `compact` (two lines) or `off` (pi's own). _project_ |
109
- | `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 |
110
- | `separator` | `"space"` | `dot`, `bar`, `slash` or `space`. _project_ |
111
- | `pathLength` | `40` | Longest the folder may be before it loses folders from the left. _project_ |
112
- | `gaugeCells` | `8` | Cells in the context gauge. `0` hides it. _project_ |
113
- | `peek` | `true` | The spinner names the state. Off, it says what pi says |
114
- | `desktop.theme` | `true` | Keep the desktop theme written. Nothing happens without the palette file |
115
- | `desktop.source` | `"~/.cache/DankMaterialShell/dms-colors.json"` | Where the palette is |
116
-
117
- ### Segments
118
-
119
- Any segment goes in any slot, in the order the slot lists them.
120
-
121
- | Id | Shows |
122
- | -------------- | ----------------------------------------------------------------------------------------------------- |
123
- | `path` | The working folder, with home as `~` |
124
- | `branch` | The branch, ahead `↑` and behind `↓`, staged `+`, modified `~`, untracked `?`, conflicts `!`, stashes |
125
- | `host` | The machine, so a pasted line says where it came from |
126
- | `session` | The session name, once it has one |
127
- | `version` | The pi version |
128
- | `clock` | The time |
129
- | `model` | `provider/model` |
130
- | `provider` | The provider on its own |
131
- | `effort` | The effort meter and level. Hidden for models that do not reason |
132
- | `context` | Context used, the gauge, tokens over the window |
133
- | `speed` | This answer's speeds, received `↓` and sent `↑` |
134
- | `wait` | Time to the first token |
135
- | `server` | The last call's time from the request leaving to the response headers |
136
- | `elapsed` | The agent's working time, as a stopwatch, and its calls |
137
- | `last` | The last finished call: its wait, its thought time and its writing speed |
138
- | `request` | This answer's tokens, with the cache |
139
- | `costRate` | This answer's cost per million tokens |
140
- | `cost` | The session's cost |
141
- | `tokens` | The session's tokens, with the cache |
142
- | `cache` | The cache hit of the last prompt |
143
- | `average` | The session's average speeds, both ways |
144
- | `statuses` | What other packages report through `setStatus`, minus the ones placed on their own |
145
- | `status:<key>` | One package's status, by the key it passes to `setStatus` |
146
-
147
- 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.
148
-
149
- ## How it fits
150
-
151
- 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.
152
-
153
- 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`.
56
+ `Alt+S` opens them, on the Look tab. You can reorder and move every piece of the strip, the frame and the footer, pick the frame style, the icons and the separator, and switch off what you do not want. The [reference](docs/reference.md#settings) lists every key and every segment.
154
57
 
155
58
  ## Credit
156
59
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@adeildo/pi-look",
3
- "version": "5.0.0",
3
+ "version": "5.1.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,7 @@
38
38
  "access": "public"
39
39
  },
40
40
  "dependencies": {
41
- "@adeildo/pi-kit": "5.0.0"
41
+ "@adeildo/pi-kit": "5.1.0"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "@earendil-works/pi-ai": "*",