useful-pi-extensions 1.11.0 → 1.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "description": "A small collection of pi extensions, installed with one command — a labelled status line with context pressure, cache, cost, effort, TTFT and tokens/sec, plus an opt-in context breakdown panel.",
   "keywords": [
     "bun",

package/packages/statusline/README.md

@@ -5,7 +5,7 @@ English | [中文](README_CN.md)
 [npm](https://www.npmjs.com/package/@reedchan/statusline) · [pi packages gallery](https://pi.dev/packages/@reedchan/statusline) · [repository](https://github.com/reedchan7/useful-pi-extensions)
 
 Replaces pi's footer with a labelled two-row one. Every value carries a word, so nothing has to
-be decoded from a symbol or remembered from a legend. `ctrl+e` opens an optional context-breakdown
+be decoded from a symbol or remembered from a legend. `ctrl+q` opens an optional context-breakdown
 panel (next section) when you want to see what is occupying the window.
 
 ```text
@@ -24,7 +24,7 @@ columns only the meter is left. Every step is a whole value — a number is neve
 | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Context window` + meter + `47%` | Share of the model's context window in use. The fill turns `warning` above 70% and `error` above 90%, the same thresholds pi's shipped footer uses, and the percentage changes color with it |
 | `471k / 1.0M`                    | Absolute context tokens over the window size. The first thing dropped when the terminal is narrow                                                                                            |
-| Breakdown panel                  | What occupies the window — opt-in via `ctrl+e` or `/breakdown` — one bucket per line under a total. See [Context breakdown](#context-breakdown)                                              |
+| Breakdown panel                  | What occupies the window — opt-in via `ctrl+q` or `/breakdown` — one bucket per line under a total. See [Context breakdown](#context-breakdown)                                              |
 | `Input` / `Output`               | Session prompt and completion tokens. `Input` counts the prompt tokens that were neither read from nor written to cache, because pi reports those two separately in the same `usage` object  |
 | `Cache hit`                      | The latest turn's cache hit rate, `cacheRead / (input + cacheRead + cacheWrite)`                                                                                                             |
 | `Cost`                           | Session cost, in USD unless a config file names another currency (see below)                                                                                                                 |
@@ -46,7 +46,7 @@ The glyphs are that preset's block fill and shaded block track, with a 1/8-cell
 
 ## Context breakdown
 
-`ctrl+e` or `/breakdown` opens an opt-in panel that answers the question the meter raises: what
+`ctrl+q` or `/breakdown` opens an opt-in panel that answers the question the meter raises: what
 is actually occupying the window. The concise footer stays the default; the choice is remembered
 in `~/.pi/agent/statusline/config.json` (`"detail": true`).
 
@@ -101,9 +101,10 @@ multi-provider). **Deferred tools** have no pi equivalent either — every activ
 always on the wire.
 
 The panel is ~50 columns wide and fits any terminal by truncating rather than by dropping
-buckets. The toggle lives on `ctrl+e` because `ctrl+j` is a bare LF in legacy terminals and reads
-as Enter; if another extension owns `ctrl+e` on your machine, the key is `BREAKDOWN_SHORTCUT` at
-the top of `index.ts`.
+buckets. The toggle lives on `ctrl+q`: `ctrl+j` is a bare LF in legacy terminals and reads
+as Enter, and `ctrl+e` is taken by pi's built-in cursor-to-line-end (`tui.editor.cursorLineEnd`);
+`ctrl+q` is unbound in pi's default keymaps. If another extension owns `ctrl+q` on your machine,
+the key is `BREAKDOWN_SHORTCUT` at the top of `index.ts`.
 
 Configuration lives at the top of [`render.ts`](render.ts):
 

package/packages/statusline/README_CN.md

@@ -5,7 +5,7 @@
 [npm](https://www.npmjs.com/package/@reedchan/statusline) · [pi packages 画廊](https://pi.dev/packages/@reedchan/statusline) · [仓库](https://github.com/reedchan7/useful-pi-extensions)
 
 替换 pi 的 footer，改成带文字标签的两行。每个值都带一个词，不需要靠符号猜、也不需要记图例。
-需要看窗口里到底装了什么时，`ctrl+e` 可打开一个可选的上下文明细面板（见下文）。
+需要看窗口里到底装了什么时，`ctrl+q` 可打开一个可选的上下文明细面板（见下文）。
 
 ```text
 Context window  █████████▍░░░░░░░░░░  47%   471k / 1.0M     Input 194k  ·  Output 89k  |  Cache hit 99.9%  |  Cost $0.23  ·  Today $1.63
@@ -23,7 +23,7 @@ LSP Active: typescript
 | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `Context window` + 仪表 + `47.1%` | 已占模型上下文窗口的比例。填充超过 70% 转 `warning`、超过 90% 转 `error`（与 pi 原生 footer 同一套阈值），百分比同步变色                |
 | `471k / 1.0M`                     | 上下文已用 token / 窗口大小。终端变窄时**第一个被舍弃**                                                                                 |
-| Breakdown 面板                    | 窗口里到底装了什么，总数领队、每桶一行——可选，`ctrl+e` 或 `/breakdown` 打开。见[上下文明细](#上下文明细)                                |
+| Breakdown 面板                    | 窗口里到底装了什么，总数领队、每桶一行——可选，`ctrl+q` 或 `/breakdown` 打开。见[上下文明细](#上下文明细)                                |
 | `Input` / `Output`                | 会话的输入与输出 token 量。`Input` 指既没命中缓存、也没写入缓存的那部分 prompt token，因为 pi 把这两种情况在同一个 `usage` 对象里分开报 |
 | `Cache hit`                       | 最近一轮的缓存命中率，`cacheRead / (input + cacheRead + cacheWrite)`                                                                    |
 | `Cost`                            | 会话花费，默认美元；配置了其他币种则换算显示（见下）                                                                                    |
@@ -44,7 +44,7 @@ LSP Active: typescript
 
 ## 上下文明细
 
-`ctrl+e` 或 `/breakdown` 打开一个可选面板，回答仪表提出的问题：窗口里到底装了什么。
+`ctrl+q` 或 `/breakdown` 打开一个可选面板，回答仪表提出的问题：窗口里到底装了什么。
 简洁两行是默认形态；开关状态记在 `~/.pi/agent/statusline/config.json`（`"detail": true`）。
 
 ```text
@@ -92,9 +92,10 @@ Claude Code 面板里有、而这里有意不做的：**Custom agents**（pi 没
 （特定厂商的订阅额度，pi 是多 provider 的）。**Deferred tools** 在 pi 里也没有对应物——
 激活工具的 schema 永远在线上。
 
-面板约 50 列宽，任何终端都放得下；放不下时逐行截断，而不是丢桶。开关键默认 `ctrl+e`——
-原本选的 `ctrl+j` 在传统终端里就是一个裸 LF，和回车无法区分；如果你的机器上 `ctrl+e`
-已被其他扩展占用，改 `index.ts` 顶部的 `BREAKDOWN_SHORTCUT` 即可。
+面板约 50 列宽，任何终端都放得下；放不下时逐行截断，而不是丢桶。开关键默认 `ctrl+q`——
+`ctrl+j` 在传统终端里是一个裸 LF，和回车无法区分，`ctrl+e` 又撞上了 pi 内建的
+光标移行尾（`tui.editor.cursorLineEnd`）；`ctrl+q` 在 pi 的默认键位里是空着的。如果你的机器上
+`ctrl+q` 已被其他扩展占用，改 `index.ts` 顶部的 `BREAKDOWN_SHORTCUT` 即可。
 
 可调项在 [`render.ts`](render.ts) 顶部：
 

package/packages/statusline/extensions/statusline/index.ts

@@ -38,10 +38,10 @@ import {
   formatCwd,
   formatLatency,
   formatTps,
+  frozenThroughput,
   avgMs,
   isQuietStatus,
   messagesTokens,
-  pair,
   cachedRates,
   ratesFromPayload,
   cacheIsFresh,
@@ -51,6 +51,7 @@ import {
   row,
   shortenPath,
   splitToolTokens,
+  timingRow,
   ttftDisplay,
   ttftMs,
   USD,
@@ -89,10 +90,12 @@ const DEFAULT_RESERVE_TOKENS = 16_384
  * The key that toggles the breakdown line; change here if another extension owns it.
  *
  * Ctrl+j was tried first and had to go: legacy terminals send it as a bare LF, which is
- * indistinguishable from Enter, so it typed newlines instead of toggling. ctrl+e is unbound across
- * pi's default keymaps and in every extension installed on this machine.
+ * indistinguishable from Enter, so it typed newlines instead of toggling. ctrl+e then collided with
+ * pi's built-in tui.editor.cursorLineEnd. ctrl+q is free: unbound in both pi-tui's TUI_KEYBINDINGS
+ * and pi's app KEYBINDINGS on macOS/Linux (only Windows maps ctrl+q, to followUp), and pi already
+ * binds ctrl+s, so the terminal runs with flow control (IXON) off and ctrl+q reaches the app.
  */
-const BREAKDOWN_SHORTCUT = 'ctrl+e'
+const BREAKDOWN_SHORTCUT = 'ctrl+q'
 const FETCH_TIMEOUT_MS = 5000
 
 function today(): string {
@@ -398,8 +401,9 @@ export default function (pi: ExtensionAPI) {
   let requestRender: (() => void) | null = null
   let currency: Currency = USD
 
-  // Latest turn reading: { rate, exact, ttftMs }
-  let reading: { rate: number; exact: boolean; ttftMs: number | null } | null = null
+  // Latest turn reading: { rate, exact, ttftMs }. rate is null when the message arrived as one
+  // burst: the honest TTFT stays, the unmeasurable throughput goes.
+  let reading: { rate: number | null; exact: boolean; ttftMs: number | null } | null = null
 
   // Breakdown-line inputs, refreshed once per turn rather than per frame. The prompt and the
   // tool list change only across turns (before_agent_start re-captures both), and the message
@@ -493,7 +497,7 @@ export default function (pi: ExtensionAPI) {
     renderedAt = 0
   }
 
-  function publish(rate: number, exact: boolean, ttft: number | null): void {
+  function publish(rate: number | null, exact: boolean, ttft: number | null): void {
     reading = { rate, exact, ttftMs: ttft }
     requestRender?.()
   }
@@ -553,9 +557,9 @@ export default function (pi: ExtensionAPI) {
     totalMeasuredOutput = num(state.totalMeasuredOutput)
     totalTtftMs = num(state.totalTtftMs)
     ttftCount = num(state.ttftCount)
-    if (isRecord(state.last) && typeof state.last.rate === 'number') {
+    if (isRecord(state.last)) {
       reading = {
-        rate: state.last.rate,
+        rate: typeof state.last.rate === 'number' ? state.last.rate : null,
         exact: state.last.exact === true,
         ttftMs: typeof state.last.ttftMs === 'number' ? state.last.ttftMs : null,
       }
@@ -599,7 +603,7 @@ export default function (pi: ExtensionAPI) {
           )
 
           // The breakdown panel sits directly under the meter it explains, before the identity
-          // row. The concise footer renders by default; ctrl+e or /breakdown opens the panel.
+          // row. The concise footer renders by default; ctrl+q or /breakdown opens the panel.
           let breakdown: string[] | null = null
           if (detailVisible) {
             const window =
@@ -618,40 +622,30 @@ export default function (pi: ExtensionAPI) {
             })
           }
 
-          // Row 2: model and the latest turn's timing on the right, path on the left. Three
-          // groups — identity, first token, throughput — separated by a wall instead of another
-          // dot, because a run of similar-looking pairs is what made the old footer unreadable.
-          const model = ctx.model?.id ?? 'no model'
-          const separator = theme.fg('dim', '  ·  ')
-          const wall = theme.fg('dim', '  |  ')
-          const identity = [theme.fg('accent', model)]
-          if (ctx.thinkingLevel) identity.push(pair(theme, 'Effort', ctx.thinkingLevel))
-
-          const ttft: string[] = []
+          // Row 2: model and the latest turn's timing on the right, path on the left. The right
+          // side assembles through timingRow's drop ladder, so a narrow terminal loses whole
+          // slots — never a half-rendered one.
           const waiting = ttftDisplay(requestAt, firstTokenAt, Date.now())
-          if (waiting !== null) {
-            // The clock is running: this wait has no reading yet, so the previous turn's
-            // numbers would only be mistaken for the current one.
-            ttft.push(pair(theme, 'TTFT', waiting.text))
-          } else if (reading) {
-            if (reading.ttftMs !== null)
-              ttft.push(pair(theme, 'TTFT', formatLatency(reading.ttftMs)))
-          }
+          // The clock is running: this wait has no reading yet, so the previous turn's numbers
+          // would only be mistaken for the current one.
+          const ttft =
+            waiting !== null
+              ? waiting.text
+              : reading && reading.ttftMs !== null
+                ? formatLatency(reading.ttftMs)
+                : null
           const avgTtft = avgMs(totalTtftMs, ttftCount)
-          if (avgTtft !== null) ttft.push(pair(theme, 'Avg TTFT', formatLatency(avgTtft)))
-
-          const throughput: string[] = []
-          if (reading) {
-            throughput.push(
-              pair(theme, 'Last', `${reading.exact ? '' : '~'}${formatTps(reading.rate)} tok/s`),
-            )
-          }
-          if (avg !== null) throughput.push(pair(theme, 'Avg', `${formatTps(avg)} tok/s`))
-
-          const row2Right = [identity, ttft, throughput]
-            .filter((group) => group.length > 0)
-            .map((group) => group.join(separator))
-            .join(wall)
+          const row2Right = timingRow(theme, width, {
+            model: ctx.model?.id ?? 'no model',
+            effort: ctx.thinkingLevel ?? null,
+            ttft,
+            avgTtft: avgTtft !== null ? formatLatency(avgTtft) : null,
+            last:
+              reading && reading.rate !== null
+                ? `${reading.exact ? '' : '~'}${formatTps(reading.rate)} tok/s`
+                : null,
+            avg: avg !== null ? `${formatTps(avg)} tok/s` : null,
+          })
           const branch = footerData.getGitBranch()
           const path = formatCwd(ctx.cwd)
           const branchSuffix = branch ? ` (${branch})` : ''
@@ -826,7 +820,8 @@ export default function (pi: ExtensionAPI) {
     const decodeMs = firstTokenAt !== null ? Date.now() - firstTokenAt : 0
     const measured = ttftMs(requestAt, firstTokenAt)
     const tokens = output > 0 ? output : totalChars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
-    if (measured !== null && decodeMs >= MIN_SAMPLE_MS) {
+    const rate = frozenThroughput(decodeMs, tokens, MIN_SAMPLE_MS)
+    if (measured !== null && rate !== null) {
       // The average's numerator and denominator must cover the same messages: totals.output spans
       // the whole session (a reload replays none of it), so pairing it with the partial denominator
       // below once produced an Avg of 4324 tok/s.
@@ -835,11 +830,14 @@ export default function (pi: ExtensionAPI) {
       totalTtftMs += measured
       ttftCount += 1
       persist(ctx.sessionManager.getSessionFile() ?? null)
-      publish((tokens / decodeMs) * 1000, output > 0, measured)
-    } else if (measured !== null && decodeMs > 0) {
-      // The frozen Last must be this message's whole-message rate, never the last live
-      // sliding-window sample: a buffered burst of chunks mid-stream reads triple.
-      publish((tokens / decodeMs) * 1000, output > 0, measured)
+      publish(rate, output > 0, measured)
+    } else if (measured !== null) {
+      // A sub-floor window is a burst arrival: the message landed in one or two chunks and there
+      // is no decode phase to measure — dividing by those milliseconds once printed Last 82000
+      // tok/s. Keep the honest TTFT, publish no rate; the live sliding-window sample is no
+      // fallback either, a buffered burst mid-stream reads triple there too.
+      publish(null, false, measured)
+      persist(ctx.sessionManager.getSessionFile() ?? null)
     }
     // Null it with the stream: a request that has produced its message is no longer in flight, and
     // a stale anchor would let the live branch count against nothing until the next turn.
@@ -848,9 +846,8 @@ export default function (pi: ExtensionAPI) {
   })
 
   // The breakdown panel is opt-in: the concise footer stays the default. Both toggles remember
-  // the choice in the config file. ctrl+e is unbound across pi's default keymaps and in every
-  // extension installed on this machine; if another extension owns it here, BREAKDOWN_SHORTCUT
-  // is the one place to move it.
+  // the choice in the config file. ctrl+q is unbound across pi's default keymaps; if another
+  // extension owns it here, BREAKDOWN_SHORTCUT is the one place to move it.
   pi.registerShortcut(BREAKDOWN_SHORTCUT, {
     description: 'Toggle the context breakdown panel in the status line',
     handler: () => {

package/packages/statusline/extensions/statusline/render.ts

@@ -85,6 +85,29 @@ export function ttftMs(requestAt: number | null, firstTokenAt: number | null): n
   return firstTokenAt > requestAt ? firstTokenAt - requestAt : null
 }
 
+/**
+ * The frozen Last throughput for a finished message: its whole-message rate, output tokens over the
+ * entire decode window.
+ *
+ * A decode window below the sample floor is a burst arrival — the whole message landed in one or
+ * two chunks, so there is no decode phase to measure. Dividing by those couple of milliseconds once
+ * printed `Last 82000 tok/s` for an 82-token greeting; like the negative TTFT above, an
+ * unmeasurable rate reports absence rather than a confident fake.
+ *
+ * @param decodeMs - Milliseconds from the first streamed delta to message end.
+ * @param tokens - Output tokens for the message (provider-reported when available).
+ * @param minSampleMs - The shortest window considered a real decode phase.
+ * @returns The tokens/second rate, or null when the window is too short to measure.
+ */
+export function frozenThroughput(
+  decodeMs: number,
+  tokens: number,
+  minSampleMs: number,
+): number | null {
+  if (decodeMs < minSampleMs) return null
+  return (tokens / decodeMs) * 1000
+}
+
 /** What the TTFT slot renders, and whether the clock is still running. */
 export interface TtftDisplay {
   text: string
@@ -419,12 +442,13 @@ export interface ContextRowParts {
  * Row 1: context pressure on the left, session totals on the right.
  *
  * Space is given up in a fixed order rather than all at once, because this row carries numbers that
- * appear nowhere else in the footer. A narrower terminal should cost the least load-bearing of them
- * visibly rather than silently dropping the whole group:
+ * appear nowhere else in the footer. A narrower terminal costs, in turn:
  *
  * 1. The absolute `tokens / window` detail,
- * 2. The input/output volumes, which are informative but not cumulative bills,
- * 3. The right group entirely (`row` then keeps the left alone).
+ * 2. The input/output volumes, which are informative but not bills,
+ * 3. The cache-hit rate, which is diagnostic rather than money,
+ * 4. Today's running total (the session's own bill outlives it),
+ * 5. The bar's own cells, down to a stub — the percent survives everything.
  *
  * @param currency - Used for the cost; defaults to USD so the row renders without a config file.
  */
@@ -441,7 +465,9 @@ export function contextRow(
     parts.percent === null ? '--' : `${Math.round(parts.percent)}%`,
   )
   // The title is Claude Code's: "Context window", so the two panels read the same at a glance.
-  const meter = `${theme.fg('dim', 'Context window')}  ${bar(theme, BAR_CELLS, fraction)}  ${percent}`
+  const meterWith = (cells: number): string =>
+    `${theme.fg('dim', 'Context window')}  ${bar(theme, cells, fraction)}  ${percent}`
+  const meter = meterWith(BAR_CELLS)
   const detail =
     parts.window > 0 ? `${formatTokens(parts.tokens)} / ${formatTokens(parts.window)}` : ''
   const withDetail = detail === '' ? meter : `${meter}   ${theme.fg('dim', detail)}`
@@ -475,9 +501,97 @@ export function contextRow(
   const fits = (left: string, right: string): boolean =>
     right === '' || visibleWidth(left) + 2 + visibleWidth(right) <= width
 
-  if (fits(withDetail, full)) return row(theme, width, withDetail, full)
-  if (fits(meter, full)) return row(theme, width, meter, full)
-  return row(theme, width, meter, core)
+  const moneyOnly = money.join(separator)
+  // The session's own bill outlives today's running total.
+  const ownBill = money.length > 0 ? (money[0] ?? '') : ''
+
+  // The ladder, highest fidelity first: the detail, the volumes, the cache diagnostics and
+  // today's total each give up their seat before the bar itself shrinks — twenty cells of bar
+  // are a luxury the bills should not have to pay for.
+  const compact = 10
+  const rungs: Array<{ left: string; right: string }> = [
+    { left: withDetail, right: full },
+    { left: meter, right: full },
+    { left: meter, right: core },
+    { left: meter, right: moneyOnly },
+    { left: meterWith(compact), right: moneyOnly },
+    { left: meterWith(compact), right: ownBill },
+  ]
+  for (const { left, right } of rungs) {
+    if (right === '' ? visibleWidth(left) <= width : fits(left, right)) {
+      return row(theme, width, left, right)
+    }
+  }
+
+  // Floor: the percent is the one number this row exists to show — the bar shrinks to a stub
+  // before the percent is ever truncated, and past that the label goes, never the number.
+  const stub = Math.min(compact, width - 22)
+  if (stub >= 4) return row(theme, width, meterWith(stub), '')
+  if (width >= 18) {
+    return row(theme, width, `${theme.fg('dim', 'Context window')}  ${percent}`, '')
+  }
+  return truncateToWidth(percent, width, theme.fg('dim', '…'))
+}
+
+/** The row-2 right side, the caller pre-formatting each slot's display text. */
+export interface TimingRowParts {
+  model: string
+  /** Thinking level label, or null to hide the slot. */
+  effort: string | null
+  /** The live TTFT clock or the frozen reading, or null to hide the slot. */
+  ttft: string | null
+  /** Session-average TTFT, or null to hide the slot. */
+  avgTtft: string | null
+  /** Last turn's decode rate, or null to hide the slot. */
+  last: string | null
+  /** Session-average decode rate, or null to hide the slot. */
+  avg: string | null
+}
+
+/**
+ * Row 2's right side: the model, the effort level, and the latest turn's timing.
+ *
+ * Like row 1, space is given up in a fixed order rather than half rendered. A narrower terminal
+ * costs, in turn: the throughput average, the TTFT average, the effort level, the last rate —
+ * aggregates before live numbers, static config before measured history. The model and the TTFT
+ * clock are the floor; past them the line truncates, because a model id is the one string here with
+ * no drop-in substitute.
+ *
+ * @returns The assembled right side, at most `width` cells wide.
+ */
+export function timingRow(theme: Theme, width: number, parts: TimingRowParts): string {
+  const separator = theme.fg('dim', '  ·  ')
+  const wall = theme.fg('dim', '  |  ')
+  const slots = {
+    model: theme.fg('accent', parts.model),
+    effort: parts.effort !== null ? pair(theme, 'Effort', parts.effort) : null,
+    ttft: parts.ttft !== null ? pair(theme, 'TTFT', parts.ttft) : null,
+    avgTtft: parts.avgTtft !== null ? pair(theme, 'Avg TTFT', parts.avgTtft) : null,
+    last: parts.last !== null ? pair(theme, 'Last', parts.last) : null,
+    avg: parts.avg !== null ? pair(theme, 'Avg', parts.avg) : null,
+  }
+
+  type Droppable = 'effort' | 'ttft' | 'avgTtft' | 'last' | 'avg'
+  const hidden = new Set<Droppable>()
+  const assemble = (): string =>
+    [
+      [slots.model, hidden.has('effort') ? null : slots.effort],
+      [hidden.has('ttft') ? null : slots.ttft, hidden.has('avgTtft') ? null : slots.avgTtft],
+      [hidden.has('last') ? null : slots.last, hidden.has('avg') ? null : slots.avg],
+    ]
+      .map((group) => group.filter((slot): slot is string => slot !== null))
+      .filter((group) => group.length > 0)
+      .map((group) => group.join(separator))
+      .join(wall)
+
+  const ladder: Droppable[] = ['avg', 'avgTtft', 'effort', 'last']
+  let right = assemble()
+  for (const key of ladder) {
+    if (visibleWidth(right) <= width) break
+    hidden.add(key)
+    right = assemble()
+  }
+  return truncateToWidth(right, width, theme.fg('dim', '…'))
 }
 
 /** `label value` where the key is quiet and the value is not. */