useful-pi-extensions 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "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.",
   "keywords": [
     "bun",

package/packages/statusline/README.md

@@ -53,29 +53,34 @@ Configuration lives at the top of [`render.ts`](render.ts):
 ## Currency
 
 pi prices every model in USD and its `cost` field carries no unit at all, so the footer cannot know
-what you were actually billed. What a session cost in RMB is set by whoever sold you the credit, not
-by a market feed, which is why the rate is configured rather than fetched.
-
-Create `~/.pi/agent/statusline.json`:
+what you were actually billed. The currency and the rate live in `~/.pi/agent/statusline.json`:
 
 ```json
 {
   "currency": {
-    "code": "CNY",
-    "perUsd": 7.12
+    "code": "CNY"
   }
 }
 ```
 
-- `code` picks the symbol (`CNY` and `RMB` give `¥`; the table also knows `USD`, `EUR`, `GBP`, `JPY`,
-  `HKD`, `TWD`, `SGD`, `KRW` and `INR`). A code the table does not know is printed as it is.
-- `symbol` overrides the table, for a currency it does not list or a different separator.
-- `perUsd` is how many units of that currency one dollar buys — the rate you were actually charged.
-  It has to be a positive number; anything else is refused and the footer stays in USD.
+Two ways to set the rate:
+
+- **Follow the market.** A `code` with no rate fetches the day's table from open.er-api.com on the
+  first session of each day and caches the whole table in the file (`rates` + `fetchedAt`), so the
+  next session starts warm and switching codes is instant and offline.
+- **Pin it.** Add `"perUsd": 7.12` and the footer always uses that rate, never touching the network
+  — the right choice when your platform bills in RMB directly, because a domestic price list is not
+  the dollar list times a market rate.
+
+`code` picks the symbol: `¥` for `CNY` and `RMB`, `JP¥` for `JPY` so the two never trade places, and
+the table also knows `USD`, `EUR`, `GBP`, `HKD`, `TWD`, `SGD`, `KRW`, `INR`, `AUD`, `CAD`, `NZD` and
+`CHF`; an unknown code is printed as it is. `symbol` overrides all of that.
 
-With the file above, the same session reads `Cost ¥1.63` instead of `Cost $0.229`. The file is read
-once per session, so edit it and `/reload`. A file that is there but unusable says so in a
-notification, rather than silently showing dollars with nothing to explain why.
+Switching is editing `code`, or `make currency CODE=JPY` from a checkout. The file is read once per
+session, so finish with `/reload`. A file that is there but unusable says so in a notification,
+rather than silently showing dollars with nothing to explain why.
+
+## Metrics
 
 ## Metrics
 

package/packages/statusline/README_CN.md

@@ -51,27 +51,31 @@ LSP Active: typescript
 ## 币种
 
 pi 里所有模型价格都是美元，而且它的 `cost` 字段**不带任何单位**，所以 footer 无从知道你实际是按什么币种付的。
-这次会话折合多少人民币，取决于卖你额度那家给的汇率，而不是市场汇率——所以汇率是**配置**出来的，不是联网抓的。
-
-创建 `~/.pi/agent/statusline.json`：
+币种与汇率放在 `~/.pi/agent/statusline.json`：
 
 ```json
 {
   "currency": {
-    "code": "CNY",
-    "perUsd": 7.12
+    "code": "CNY"
   }
 }
 ```
 
-- `code` 决定符号（`CNY` 与 `RMB` 得到 `¥`；符号表还认 `USD`、`EUR`、`GBP`、`JPY`、`HKD`、`TWD`、
-  `SGD`、`KRW`、`INR`）。表里没有的代码就原样打印。
-- `symbol` 可覆盖符号表，用于表里没列的币种，或想换分隔方式。
-- `perUsd` 是一美元等于多少该币种，也就是**你实际被收的汇率**。必须是正数；
-  否则整块被拒绝，footer 继续显示美元。
+汇率有两种设法：
+
+- **跟随市场。** 只写 `code` 不写汇率时，每天第一个会话会从 open.er-api.com 拉取当日汇率表，
+  并把整张表缓存进文件（`rates` + `fetchedAt`），下个会话热启动；切换币种即时生效、离线也能切。
+- **钉死。** 加上 `"perUsd": 7.12`，footer 永远用这个汇率、绝不联网——如果你的平台直接按人民币计费，
+  这是正确选择：国内价目表不是美元价目表乘以市场汇率。
+
+`code` 决定符号：`CNY` 和 `RMB` 得到 `¥`，`JPY` 得到 `JP¥`（两者永不混用），符号表还认 `USD`、
+`EUR`、`GBP`、`HKD`、`TWD`、`SGD`、`KRW`、`INR`、`AUD`、`CAD`、`NZD`、`CHF`；表里没有的代码原样打印。
+`symbol` 可覆盖这一切。
 
-配置成上面这样，同一个会话就从 `Cost $0.229` 变成 `Cost ¥1.63`。该文件每个会话只读一次，
-改完需 `/reload`。文件存在但不可用时会给出通知，而不是静默继续显示美元。
+切换就是改 `code`，或者在检出里执行 `make currency CODE=JPY`。该文件每个会话只读一次，改完需 `/reload`。
+文件存在但不可用时会给出通知，而不是静默继续显示美元。
+
+## 指标口径
 
 ## 指标口径
 

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

@@ -30,6 +30,7 @@ import type {
 import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
 
 import {
+  avgTokPerSec,
   contextRow,
   currencyFromConfig,
   formatCwd,
@@ -37,10 +38,10 @@ import {
   formatTps,
   isQuietStatus,
   pair,
-  rateFromPayload,
-  cachedRate,
+  cachedRates,
+  ratesFromPayload,
   cacheIsFresh,
-  withCachedRate,
+  withCachedRates,
   row,
   shortenPath,
   ttftDisplay,
@@ -59,7 +60,7 @@ const FALLBACK_TOKENS_PER_CHAR = 0.25
 
 /** The status line's own settings file, alongside pi's other per-tool config. */
 const CONFIG_PATH = join(homedir(), '.pi', 'agent', 'statusline.json')
-/** Free, keyless, updated once a day — which is exactly the freshness a daily rate wants. */
+/** Free, keyless, and one request returns every currency — so the cache serves instant switching. */
 const RATES_URL = 'https://open.er-api.com/v6/latest/USD'
 const FETCH_TIMEOUT_MS = 5000
 
@@ -70,13 +71,14 @@ function today(): string {
   return `${now.getFullYear()}-${month}-${day}`
 }
 
-async function fetchRate(code: string): Promise<number | null> {
+async function fetchRates(): Promise<Record<string, number> | null> {
   const controller = new AbortController()
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
   try {
     const response = await fetch(RATES_URL, { signal: controller.signal })
     if (!response.ok) return null
-    return rateFromPayload(await response.json(), code)
+    const rates = ratesFromPayload(await response.json())
+    return Object.keys(rates).length === 0 ? null : rates
   } catch {
     return null
   } finally {
@@ -87,6 +89,11 @@ async function fetchRate(code: string): Promise<number | null> {
 /**
  * Reads the display currency.
  *
+ * `perUsd` is a pinned rate and wins untouched; a code without one resolves through the cached rate
+ * table — today's table answers instantly, a stale one answers while a fresh one is fetched, and
+ * only a first-ever failure speaks up. The whole table is cached because one request returns every
+ * currency, which is also what makes switching codes instant and offline.
+ *
  * Called once per session on purpose: a footer that stat'ed a file on every frame would be its own
  * bug. Editing the file therefore takes effect on `/reload`.
  */
@@ -102,21 +109,22 @@ async function loadCurrency(notify: (message: string) => void): Promise<Currency
   if (problem !== null) notify(problem)
   if (pending === null) return currency
 
-  const cached = cachedRate(text)
-  if (cached !== null && cacheIsFresh(cached.fetchedAt, today())) {
-    return { symbol: pending.symbol, perUsd: cached.perUsd }
+  const cached = cachedRates(text)
+  const known = cached?.rates[pending.code]
+  if (cached !== null && known !== undefined && cacheIsFresh(cached.fetchedAt, today())) {
+    return { symbol: pending.symbol, perUsd: known }
   }
 
-  const fetched = await fetchRate(pending.code)
+  const fetched = await fetchRates()
   if (fetched !== null) {
     try {
-      await writeFile(CONFIG_PATH, withCachedRate(text, fetched, today()))
+      await writeFile(CONFIG_PATH, withCachedRates(text, fetched, today()))
     } catch {
       // The session still runs on the fetched rate; only tomorrow's warm start is lost.
     }
-    return { symbol: pending.symbol, perUsd: fetched }
+    return { symbol: pending.symbol, perUsd: fetched[pending.code] ?? USD.perUsd }
   }
-  if (cached !== null) return { symbol: pending.symbol, perUsd: cached.perUsd }
+  if (known !== undefined) return { symbol: pending.symbol, perUsd: known }
   notify(`could not fetch a ${pending.code} rate, showing USD`)
   return USD
 }
@@ -231,6 +239,7 @@ export default function (pi: ExtensionAPI) {
   let chars = 0
   let requestAt: number | null = null
   let firstTokenAt: number | null = null
+  let totalDecodeMs = 0
   let ticker: ReturnType<typeof setInterval> | null = null
   let windowAt = 0
   let windowTokens = 0
@@ -281,6 +290,7 @@ export default function (pi: ExtensionAPI) {
         render(width: number): string[] {
           const usage = ctx.getContextUsage()
           const totals = collectTotals(ctx)
+          const avg = avgTokPerSec(totals.output, totalDecodeMs)
           const row1 = contextRow(
             theme,
             width,
@@ -309,12 +319,15 @@ export default function (pi: ExtensionAPI) {
             if (reading.ttftMs !== null)
               row2Parts.push(pair(theme, 'TTFT', formatLatency(reading.ttftMs), 'muted'))
             row2Parts.push(
-              theme.fg(
-                reading.exact ? 'success' : 'dim',
+              pair(
+                theme,
+                'Last',
                 `${reading.exact ? '' : '~'}${formatTps(reading.rate)} tok/s`,
+                reading.exact ? 'success' : 'dim',
               ),
             )
           }
+          if (avg !== null) row2Parts.push(pair(theme, 'Avg', `${formatTps(avg)} tok/s`, 'muted'))
           const row2Right = row2Parts.join(theme.fg('dim', '  ·  '))
 
           const branch = footerData.getGitBranch()
@@ -374,6 +387,7 @@ export default function (pi: ExtensionAPI) {
     ratio = seedRatio(ctx)
     reading = null
     requestAt = null
+    totalDecodeMs = 0
     stopTicker()
     resetStream()
     currency = await loadCurrency((message) => ctx.ui.notify(message, 'warning'))
@@ -455,8 +469,11 @@ 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)
+    if (measured !== null && decodeMs >= MIN_SAMPLE_MS) {
+      // Session-average numerator lives in collectTotals; this is its denominator.
+      totalDecodeMs += decodeMs
       publish((tokens / decodeMs) * 1000, output > 0, measured)
+    }
     // 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.
     requestAt = null

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

@@ -143,13 +143,18 @@ export const USD: Currency = { symbol: '$', perUsd: 1 }
 
 /** Currencies the config can name by `code` alone. Anything else needs an explicit `symbol`. */
 const CURRENCY_SYMBOLS: Record<string, string> = {
+  AUD: 'A$',
+  CAD: 'CA$',
+  CHF: 'CHF',
   CNY: '¥',
   EUR: '€',
   GBP: '£',
   HKD: 'HK$',
   INR: '₹',
-  JPY: '¥',
+  // ¥ is CNY's by default; JPY wears the prefixed form so the two never trade places.
+  JPY: 'JP¥',
   KRW: '₩',
+  NZD: 'NZ$',
   RMB: '¥',
   SGD: 'S$',
   TWD: 'NT$',
@@ -250,26 +255,34 @@ export function currencyFromConfig(text: string | null): CurrencyConfig {
   }
 }
 
-/** One rate out of an open.er-api.com payload (`{"rates": {"CNY": 7.12}}`), read defensively. */
-export function rateFromPayload(payload: unknown, code: string): number | null {
-  if (!isRecord(payload) || !isRecord(payload.rates)) return null
-  const rate = payload.rates[code]
-  return typeof rate === 'number' && Number.isFinite(rate) && rate > 0 ? rate : null
+/** The day's rates out of an open.er-api.com payload, positive and finite only. */
+export function ratesFromPayload(payload: unknown): Record<string, number> {
+  if (!isRecord(payload) || !isRecord(payload.rates)) return {}
+  const rates: Record<string, number> = {}
+  for (const [code, rate] of Object.entries(payload.rates)) {
+    if (typeof rate === 'number' && Number.isFinite(rate) && rate > 0) rates[code] = rate
+  }
+  return rates
 }
 
-/** The rate a config file cached from an earlier fetch, and the day it was fetched. */
-export function cachedRate(text: string): { perUsd: number; fetchedAt: string } | null {
+/** The rates a config file cached from an earlier fetch, and the day they were fetched. */
+export function cachedRates(
+  text: string,
+): { rates: Record<string, number>; fetchedAt: string } | null {
   let config: unknown
   try {
     config = JSON.parse(text)
   } catch {
     return null
   }
-  if (!isRecord(config)) return null
-  const perUsd = config.fetchedPerUsd
+  if (!isRecord(config) || !isRecord(config.rates)) return null
   const fetchedAt = config.fetchedAt
-  if (typeof perUsd !== 'number' || !Number.isFinite(perUsd) || perUsd <= 0) return null
-  return typeof fetchedAt === 'string' ? { perUsd, fetchedAt } : null
+  if (typeof fetchedAt !== 'string') return null
+  const rates: Record<string, number> = {}
+  for (const [code, rate] of Object.entries(config.rates)) {
+    if (typeof rate === 'number' && Number.isFinite(rate) && rate > 0) rates[code] = rate
+  }
+  return Object.keys(rates).length === 0 ? null : { rates, fetchedAt }
 }
 
 /** Whether a cached rate was fetched today, both dates as `YYYY-MM-DD`. */
@@ -277,13 +290,23 @@ export function cacheIsFresh(fetchedAt: string, today: string): boolean {
   return fetchedAt.slice(0, 10) === today
 }
 
+/** Session-average output tokens per second of measured decode time; null before any measurement. */
+export function avgTokPerSec(outputTokens: number, decodeMs: number): number | null {
+  if (decodeMs <= 0) return null
+  return outputTokens / (decodeMs / 1000)
+}
+
 /**
- * The config file's text with a fetched rate recorded in it, so the next session starts warm.
+ * The config file's text with the day's rates recorded in it, so the next session starts warm.
  *
  * Unknown keys are kept, and a file that does not parse is returned untouched: the extension has no
  * business replacing a config it could not read with one it wrote.
  */
-export function withCachedRate(text: string, perUsd: number, fetchedAt: string): string {
+export function withCachedRates(
+  text: string,
+  rates: Record<string, number>,
+  fetchedAt: string,
+): string {
   let config: unknown
   try {
     config = JSON.parse(text)
@@ -291,7 +314,7 @@ export function withCachedRate(text: string, perUsd: number, fetchedAt: string):
     return text
   }
   if (!isRecord(config)) return text
-  return `${JSON.stringify({ ...config, fetchedPerUsd: perUsd, fetchedAt }, null, 2)}\n`
+  return `${JSON.stringify({ ...config, rates, fetchedAt }, null, 2)}\n`
 }
 
 /** Three decimals, with one trailing zero trimmed so `$0.380` renders as `$0.38`. */