useful-pi-extensions 1.1.2 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.1.2",
+  "version": "1.3.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'
 
@@ -37,8 +37,13 @@ import {
   formatTps,
   isQuietStatus,
   pair,
+  rateFromPayload,
+  cachedRate,
+  cacheIsFresh,
+  withCachedRate,
   row,
   shortenPath,
+  ttftDisplay,
   ttftMs,
   USD,
   type Currency,
@@ -47,11 +52,37 @@ import {
 const LIVE_RENDER_MS = 200
 const WINDOW_MS = 2000
 const MIN_SAMPLE_MS = 200
+/** How often the waiting TTFT slot ticks while a request is in flight. */
+const TICK_MS = 250
 /** Pi's own estimateTokens() heuristic, used only until a real ratio is known. */
 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. */
+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 fetchRate(code: string): Promise<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)
+  } catch {
+    return null
+  } finally {
+    clearTimeout(timer)
+  }
+}
 
 /**
  * Reads the display currency.
@@ -60,22 +91,34 @@ const CONFIG_PATH = join(homedir(), '.pi', 'agent', 'statusline.json')
  * 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 = cachedRate(text)
+  if (cached !== null && cacheIsFresh(cached.fetchedAt, today())) {
+    return { symbol: pending.symbol, perUsd: cached.perUsd }
+  }
+
+  const fetched = await fetchRate(pending.code)
+  if (fetched !== null) {
+    try {
+      await writeFile(CONFIG_PATH, withCachedRate(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 }
+  }
+  if (cached !== null) return { symbol: pending.symbol, perUsd: cached.perUsd }
+  notify(`could not fetch a ${pending.code} rate, showing USD`)
+  return USD
 }
 
 /** A content block as providers stream it; every field is read defensively. */
@@ -188,6 +231,7 @@ export default function (pi: ExtensionAPI) {
   let chars = 0
   let requestAt: number | null = null
   let firstTokenAt: number | null = null
+  let ticker: ReturnType<typeof setInterval> | null = null
   let windowAt = 0
   let windowTokens = 0
   let renderedAt = 0
@@ -205,6 +249,26 @@ export default function (pi: ExtensionAPI) {
     requestRender?.()
   }
 
+  /** Stops the live count; a frozen TTFT needs no clock. */
+  function stopTicker(): void {
+    if (ticker !== null) {
+      clearInterval(ticker)
+      ticker = null
+    }
+  }
+
+  /** Ticks the footer while a request is in flight, until the first token lands or the turn ends. */
+  function startTicker(): void {
+    if (ticker !== null) return
+    ticker = setInterval(() => {
+      if (requestAt === null || firstTokenAt !== null) {
+        stopTicker()
+        return
+      }
+      requestRender?.()
+    }, TICK_MS)
+  }
+
   function installFooter(ctx: ExtensionContext): void {
     ctx.ui.setFooter((tui, theme, footerData: ReadonlyFooterDataProvider) => {
       requestRender = () => tui.requestRender()
@@ -236,7 +300,12 @@ export default function (pi: ExtensionAPI) {
           const model = ctx.model?.id ?? 'no model'
           const row2Parts = [theme.fg('accent', model)]
           if (ctx.thinkingLevel) row2Parts.push(pair(theme, 'Effort', ctx.thinkingLevel, 'muted'))
-          if (reading) {
+          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
+            // throughput would only be mistaken for the current one.
+            row2Parts.push(pair(theme, 'TTFT', waiting.text, 'muted'))
+          } else if (reading) {
             if (reading.ttftMs !== null)
               row2Parts.push(pair(theme, 'TTFT', formatLatency(reading.ttftMs), 'muted'))
             row2Parts.push(
@@ -284,10 +353,28 @@ export default function (pi: ExtensionAPI) {
     })
   }
 
+  // A run that ends without a first token (abort, provider error) must not leave a clock counting
+  // against a request that is no longer in flight.
+  pi.on('turn_end', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('agent_end', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('agent_settled', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
   pi.on('session_start', async (_event, ctx) => {
     ratio = seedRatio(ctx)
     reading = null
     requestAt = null
+    stopTicker()
     resetStream()
     currency = await loadCurrency((message) => ctx.ui.notify(message, 'warning'))
     installFooter(ctx)
@@ -309,6 +396,16 @@ export default function (pi: ExtensionAPI) {
     requestAt = Date.now()
   })
 
+  pi.on('turn_start', async () => {
+    requestAt = null
+    stopTicker()
+  })
+
+  pi.on('before_provider_request', async () => {
+    requestAt = Date.now()
+    startTicker()
+  })
+
   pi.on('message_update', async (event) => {
     const delta = event.assistantMessageEvent
     // Narrowing on the discriminant is what keeps the payload typed; membership in
@@ -322,7 +419,10 @@ export default function (pi: ExtensionAPI) {
     }
 
     const now = Date.now()
-    if (firstTokenAt === null) firstTokenAt = now
+    if (firstTokenAt === null) {
+      firstTokenAt = now
+      stopTicker()
+    }
     chars += delta.delta.length
 
     const tokens = chars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
@@ -357,6 +457,9 @@ export default function (pi: ExtensionAPI) {
     const tokens = output > 0 ? output : totalChars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
     if (measured !== null && decodeMs >= MIN_SAMPLE_MS)
       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
     resetStream()
   })
 }

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

@@ -81,6 +81,36 @@ export function ttftMs(requestAt: number | null, firstTokenAt: number | null): n
   return firstTokenAt > requestAt ? firstTokenAt - requestAt : null
 }
 
+/** What the TTFT slot renders, and whether the clock is still running. */
+export interface TtftDisplay {
+  text: string
+  live: boolean
+}
+
+/**
+ * The TTFT slot, for all three phases of a request.
+ *
+ * While the request is in flight the slot counts up (`~2s`, the `~` marking an unfinished wait, the
+ * same convention as the tok/s estimate) — a slow first byte is something you watch happen, not a
+ * number you are told about afterwards. The moment the first token lands the count freezes into the
+ * exact value. With no request in flight there is nothing to show.
+ *
+ * @param now - The clock, passed in so every branch stays a function of its arguments.
+ */
+export function ttftDisplay(
+  requestAt: number | null,
+  firstTokenAt: number | null,
+  now: number,
+): TtftDisplay | null {
+  if (requestAt === null) return null
+  if (firstTokenAt === null) {
+    if (now < requestAt) return null
+    return { text: `~${formatLatency(now - requestAt)}`, live: true }
+  }
+  const measured = ttftMs(requestAt, firstTokenAt)
+  return measured === null ? null : { text: formatLatency(measured), live: false }
+}
+
 /** Home-relative path, or the absolute path when it is outside the home directory. */
 export function formatCwd(cwd: string): string {
   const home = homedir()
@@ -139,48 +169,129 @@ 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',
+  }
+}
+
+/** 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 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 {
+  let config: unknown
+  try {
+    config = JSON.parse(text)
+  } catch {
+    return null
+  }
+  if (!isRecord(config)) return null
+  const perUsd = config.fetchedPerUsd
+  const fetchedAt = config.fetchedAt
+  if (typeof perUsd !== 'number' || !Number.isFinite(perUsd) || perUsd <= 0) return null
+  return typeof fetchedAt === 'string' ? { perUsd, fetchedAt } : null
+}
+
+/** 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
+}
+
+/**
+ * The config file's text with a fetched rate 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 {
+  let config: unknown
+  try {
+    config = JSON.parse(text)
+  } catch {
+    return text
+  }
+  if (!isRecord(config)) return text
+  return `${JSON.stringify({ ...config, fetchedPerUsd: perUsd, fetchedAt }, null, 2)}\n`
 }
 
 /** Three decimals, with one trailing zero trimmed so `$0.380` renders as `$0.38`. */