useful-pi-extensions 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.2.0",
+  "version": "1.4.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/extensions/statusline/index.ts

@@ -18,7 +18,7 @@
  * stepStartTime; decodeMs = completedTime - firstTokenTime; tok/s = usage.output / (decodeMs / 1000)
  */
 
-import { readFile, stat } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 
@@ -30,6 +30,7 @@ import type {
 import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
 
 import {
+  avgTokPerSec,
   contextRow,
   currencyFromConfig,
   formatCwd,
@@ -37,6 +38,10 @@ import {
   formatTps,
   isQuietStatus,
   pair,
+  cachedRates,
+  ratesFromPayload,
+  cacheIsFresh,
+  withCachedRates,
   row,
   shortenPath,
   ttftDisplay,
@@ -55,30 +60,73 @@ 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, 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
+
+function today(): string {
+  const now = new Date()
+  const month = String(now.getMonth() + 1).padStart(2, '0')
+  const day = String(now.getDate()).padStart(2, '0')
+  return `${now.getFullYear()}-${month}-${day}`
+}
+
+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
+    const rates = ratesFromPayload(await response.json())
+    return Object.keys(rates).length === 0 ? null : rates
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
 
 /**
  * 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`.
  */
 async function loadCurrency(notify: (message: string) => void): Promise<Currency> {
-  try {
-    await stat(CONFIG_PATH)
-  } catch {
-    // No config file is the normal case, and it means USD.
-    return USD
-  }
-  let text: string
+  let text: string | null = null
   try {
     text = await readFile(CONFIG_PATH, 'utf8')
   } catch {
-    notify('statusline.json exists but could not be read, showing USD')
+    // No config file is the normal case, and it means USD.
     return USD
   }
-  const { currency, problem } = currencyFromConfig(text)
+  const { currency, pending, problem } = currencyFromConfig(text)
   if (problem !== null) notify(problem)
-  return currency
+  if (pending === null) return currency
+
+  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 fetchRates()
+  if (fetched !== null) {
+    try {
+      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[pending.code] ?? USD.perUsd }
+  }
+  if (known !== undefined) return { symbol: pending.symbol, perUsd: known }
+  notify(`could not fetch a ${pending.code} rate, showing USD`)
+  return USD
 }
 
 /** A content block as providers stream it; every field is read defensively. */
@@ -191,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
@@ -241,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,
@@ -269,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()
@@ -334,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'))
@@ -415,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

@@ -169,48 +169,147 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  * @param raw - The `currency` value from a parsed config file.
  * @returns The currency, or null when the block could not be used.
  */
+/** The identity a currency block asks for: the API code and the symbol to print. */
+interface CurrencyIdentity {
+  code: string
+  symbol: string
+}
+
+function currencyIdentity(raw: Record<string, unknown>): CurrencyIdentity | null {
+  const code = typeof raw.code === 'string' ? raw.code.trim().toUpperCase() : ''
+  const explicit = typeof raw.symbol === 'string' ? raw.symbol : ''
+  const symbol = explicit || CURRENCY_SYMBOLS[code] || code
+  return symbol === '' ? null : { code, symbol }
+}
+
 export function parseCurrency(raw: unknown): Currency | null {
   if (!isRecord(raw)) return null
   const rate = raw.perUsd
   if (typeof rate !== 'number' || !Number.isFinite(rate) || rate <= 0) return null
-  const code = typeof raw.code === 'string' ? raw.code.trim().toUpperCase() : ''
-  const explicit = typeof raw.symbol === 'string' ? raw.symbol : ''
-  const symbol = explicit || CURRENCY_SYMBOLS[code] || code
-  return symbol === '' ? null : { symbol, perUsd: rate }
+  const identity = currencyIdentity(raw)
+  return identity === null ? null : { symbol: identity.symbol, perUsd: rate }
 }
 
-/** A currency, plus the message to show when the config named one that could not be used. */
+/** A currency, plus what to do when the config named one without a rate of its own. */
 export interface CurrencyConfig {
   currency: Currency
+  /** Set when the block names a code but no rate: the rate comes from a daily fetch. */
+  pending: { code: string; symbol: string } | null
   problem: string | null
 }
 
 /**
  * The display currency a config file asks for.
  *
+ * A block with `perUsd` is a rate the user pinned, and is used as it is. A block with only a `code`
+ * asks for the market rate, which the caller fetches once a day — this returns what to fetch and
+ * the symbol to spend it with, and the caller decides what a failed fetch falls back to.
+ *
  * @param text - The contents of the config file, or null when it does not exist. Absent is the
  *   normal case and is not a problem; a file that is there but unusable is, because the footer
  *   would otherwise keep showing dollars with nothing to explain it.
  */
 export function currencyFromConfig(text: string | null): CurrencyConfig {
-  if (text === null) return { currency: USD, problem: null }
+  if (text === null) return { currency: USD, pending: null, problem: null }
   let config: unknown
   try {
     config = JSON.parse(text)
   } catch {
-    return { currency: USD, problem: 'statusline.json is not valid JSON, showing USD' }
+    return {
+      currency: USD,
+      pending: null,
+      problem: 'statusline.json is not valid JSON, showing USD',
+    }
   }
   if (!isRecord(config) || !Object.hasOwn(config, 'currency')) {
-    return { currency: USD, problem: null }
+    return { currency: USD, pending: null, problem: null }
   }
-  const currency = parseCurrency(config.currency)
-  if (currency === null) {
+  if (!isRecord(config.currency)) {
     return {
       currency: USD,
-      problem: 'statusline.json currency needs a positive perUsd, showing USD',
+      pending: null,
+      problem: 'statusline.json currency needs a code with a rate, or perUsd, showing USD',
+    }
+  }
+  const identity = currencyIdentity(config.currency)
+  const rate = config.currency.perUsd
+  if (typeof rate === 'number' && Number.isFinite(rate) && rate > 0) {
+    return {
+      currency: { symbol: identity?.symbol ?? '$', perUsd: rate },
+      pending: null,
+      problem: null,
     }
   }
-  return { currency, problem: null }
+  if (identity !== null && !Object.hasOwn(config.currency, 'perUsd')) {
+    return { currency: USD, pending: identity, problem: null }
+  }
+  return {
+    currency: USD,
+    pending: null,
+    problem: 'statusline.json currency needs a code with a rate, or perUsd, showing USD',
+  }
+}
+
+/** 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 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) || !isRecord(config.rates)) return null
+  const fetchedAt = config.fetchedAt
+  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`. */
+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 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 withCachedRates(
+  text: string,
+  rates: Record<string, number>,
+  fetchedAt: string,
+): string {
+  let config: unknown
+  try {
+    config = JSON.parse(text)
+  } catch {
+    return text
+  }
+  if (!isRecord(config)) return text
+  return `${JSON.stringify({ ...config, rates, fetchedAt }, null, 2)}\n`
 }
 
 /** Three decimals, with one trailing zero trimmed so `$0.380` renders as `$0.38`. */