useful-pi-extensions 1.11.1 → 1.11.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.11.1",
+  "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/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,
@@ -400,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
@@ -495,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?.()
   }
@@ -555,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,
       }
@@ -620,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})` : ''
@@ -828,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.
@@ -837,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.

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. */