useful-pi-extensions 1.0.0 → 1.1.0

package/README.md

@@ -5,15 +5,18 @@ English | [中文](README_CN.md)
 A small collection of [pi](https://pi.dev) extensions, installed with one command. Every extension
 in it is also published on its own, so you can take the collection or just the piece you want.
 
+- `useful-pi-extensions`, the collection — [npm](https://www.npmjs.com/package/useful-pi-extensions) · [pi packages gallery](https://pi.dev/packages/useful-pi-extensions)
+- `@reedchan/statusline` — [npm](https://www.npmjs.com/package/@reedchan/statusline) · [pi packages gallery](https://pi.dev/packages/@reedchan/statusline)
+
 ```sh
 pi install npm:useful-pi-extensions
 ```
 
 ## What is in here
 
-| Extension                                               | What it does                                                                                                                                                                                            |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@reedchan/statusline`](packages/statusline/README.md) | Replaces pi's footer with a labelled two-row one: context pressure as a fixed-size meter, cache and cost, the model and effort level, and the latest turn's TTFT and decode throughput in tokens/second |
+| Extension                                               | What it does                                                                                                                                                                                                                                                                             |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@reedchan/statusline`](packages/statusline/README.md) | Replaces pi's footer with a labelled two-row one: context pressure as a fixed-size meter, the session's input/output tokens, cache hit rate and cost (in whatever currency you configure), the model and effort level, and the latest turn's TTFT and decode throughput in tokens/second |
 
 Only one extension owns the footer, so `statusline` is a complete replacement rather than an
 addition. If you want pi's stock footer back, remove this package and `/reload`.

package/README_CN.md

@@ -5,15 +5,18 @@
 一组 [pi](https://pi.dev) 扩展，一行命令即可安装。其中的每个扩展也会单独发布，
 所以你要么整套装，要么只取其中一件。
 
+- `useful-pi-extensions`（合集）— [npm](https://www.npmjs.com/package/useful-pi-extensions) · [pi packages 画廊](https://pi.dev/packages/useful-pi-extensions)
+- `@reedchan/statusline` — [npm](https://www.npmjs.com/package/@reedchan/statusline) · [pi packages 画廊](https://pi.dev/packages/@reedchan/statusline)
+
 ```sh
 pi install npm:useful-pi-extensions
 ```
 
 ## 包含什么
 
-| 扩展                                                       | 作用                                                                                                                                           |
-| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`@reedchan/statusline`](packages/statusline/README_CN.md) | 替换 pi 的 footer，改成带文字标签的两行：上下文压力用固定宽度仪表显示，外加缓存与花费、模型与思考等级，以及最近一轮的 TTFT 和解码速度（tok/s） |
+| 扩展                                                       | 作用                                                                                                                                                                                             |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [`@reedchan/statusline`](packages/statusline/README_CN.md) | 替换 pi 的 footer，改成带文字标签的两行：上下文压力用固定宽度仪表显示，外加本次会话的输入/输出 token 量、缓存命中率与花费（币种可配置）、模型与思考等级，以及最近一轮的 TTFT 和解码速度（tok/s） |
 
 footer 只能有一个扩展占用，所以 `statusline` 是**替换**而不是叠加。想回到 pi 原生 footer，移除本包再 `/reload`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "useful-pi-extensions",
-  "version": "1.0.0",
+  "version": "1.1.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",
@@ -19,6 +19,7 @@
     "url": "https://github.com/reedchan7/useful-pi-extensions/issues"
   },
   "license": "MIT",
+  "author": "Reed Chan <xinyuchen77@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reedchan7/useful-pi-extensions.git"

package/packages/statusline/README.md

@@ -2,22 +2,30 @@
 
 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.
 
 ```
-Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M          Cache 38M · Hit 100.0% · Cost $0.56
-~/.pi (master)              deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
+Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M                   Input 194k  ·  Output 89k  ·  Cache hit 99.9%  ·  Cost $0.229
+~/.pi (master)                                                               deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
 LSP Active: typescript
 ```
 
+A narrower terminal gives the row up in a fixed order rather than all at once: the `471k / 1.0M`
+detail goes first, then the input/output volumes, leaving the hit rate and the bill. Below about 60
+columns only the meter is left. Every step is a whole value — a number is never shown cut in half.
+
 ## What each part is
 
 | Part                        | Meaning                                                                                                                                                                                      |
 | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `Context` + meter + `47.1%` | 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. Dropped first when the terminal is narrow                                                                                                      |
-| `Cache` / `Hit` / `Cost`    | Cumulative prompt-cache reads, the latest turn's cache hit rate (`cacheRead / (input + cacheRead + cacheWrite)`), and session cost                                                           |
+| `471k / 1.0M`               | Absolute context tokens over the window size. The first thing dropped when the terminal is narrow                                                                                            |
+| `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)                                                                                                                 |
 | Effort                      | The active thinking level                                                                                                                                                                    |
 | `TTFT`                      | Time from request dispatch to the first streamed token                                                                                                                                       |
 | `tok/s`                     | Decode throughput, i.e. output tokens per second of decode time                                                                                                                              |
@@ -42,6 +50,33 @@ Configuration lives at the top of [`render.ts`](render.ts):
 | `BAR_TRACK`    | `░`     | Set to `""` for a trackless meter, or `"─"` for a hairline one                    |
 | `QUIET_STATUS` | pi-lens | `[statusKey, pattern]` pairs whose matching text is hidden as "nothing to report" |
 
+## 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`:
+
+```json
+{
+  "currency": {
+    "code": "CNY",
+    "perUsd": 7.12
+  }
+}
+```
+
+- `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.
+
+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.
+
 ## Metrics
 
 Throughput and latency follow the

package/packages/statusline/README_CN.md

@@ -2,25 +2,33 @@
 
 [English](README.md) | 中文
 
+[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，改成带文字标签的两行。每个值都带一个词，不需要靠符号猜、也不需要记图例。
 
 ```
-Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M          Cache 38M · Hit 100.0% · Cost $0.56
-~/.pi (master)              deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
+Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M                   Input 194k  ·  Output 89k  ·  Cache hit 99.9%  ·  Cost $0.229
+~/.pi (master)                                                               deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
 LSP Active: typescript
 ```
 
+终端变窄时，这一行是**按固定顺序**逐项舍弃的，而不是整体消失：先丢 `471k / 1.0M`，
+再丢输入/输出量，最后保留命中率与花费。窄于约 60 列时就只剩仪表了。
+每一步丢的都是完整的一项，绝不出现被截掉一半的数字。
+
 ## 每一项是什么
 
-| 部分                       | 含义                                                                                                                     |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `Context` + 仪表 + `47.1%` | 已占模型上下文窗口的比例。填充超过 70% 转 `warning`、超过 90% 转 `error`（与 pi 原生 footer 同一套阈值），百分比同步变色 |
-| `471k / 1.0M`              | 上下文已用 token / 窗口大小。终端变窄时**优先丢弃**这一项                                                                |
-| `Cache` / `Hit` / `Cost`   | 累计 prompt cache 读取量、最近一轮缓存命中率（`cacheRead / (input + cacheRead + cacheWrite)`）、会话花费                 |
-| Effort                     | 当前思考等级                                                                                                             |
-| `TTFT`                     | 从发出请求到第一个流式 token 的耗时                                                                                      |
-| `tok/s`                    | 解码吞吐，即每秒解码时间产出的输出 token 数                                                                              |
-| 最后一行                   | 其他扩展通过 `ctx.ui.setStatus()` 设的状态，否则它们会静默消失                                                           |
+| 部分                       | 含义                                                                                                                                    |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `Context` + 仪表 + `47.1%` | 已占模型上下文窗口的比例。填充超过 70% 转 `warning`、超过 90% 转 `error`（与 pi 原生 footer 同一套阈值），百分比同步变色                |
+| `471k / 1.0M`              | 上下文已用 token / 窗口大小。终端变窄时**第一个被舍弃**                                                                                 |
+| `Input` / `Output`         | 会话的输入与输出 token 量。`Input` 指既没命中缓存、也没写入缓存的那部分 prompt token，因为 pi 把这两种情况在同一个 `usage` 对象里分开报 |
+| `Cache hit`                | 最近一轮的缓存命中率，`cacheRead / (input + cacheRead + cacheWrite)`                                                                    |
+| `Cost`                     | 会话花费，默认美元；配置了其他币种则换算显示（见下）                                                                                    |
+| Effort                     | 当前思考等级                                                                                                                            |
+| `TTFT`                     | 从发出请求到第一个流式 token 的耗时                                                                                                     |
+| `tok/s`                    | 解码吞吐，即每秒解码时间产出的输出 token 数                                                                                             |
+| 最后一行                   | 其他扩展通过 `ctx.ui.setStatus()` 设的状态，否则它们会静默消失                                                                          |
 
 ## 关于这个仪表
 
@@ -40,6 +48,31 @@ LSP Active: typescript
 | `BAR_TRACK`    | `░`     | 设为 `""` 得到无轨道仪表，设为 `"─"` 得到细线轨道       |
 | `QUIET_STATUS` | pi-lens | `[状态键, 正则]` 列表，匹配到的文本视为"无事发生"而隐藏 |
 
+## 币种
+
+pi 里所有模型价格都是美元，而且它的 `cost` 字段**不带任何单位**，所以 footer 无从知道你实际是按什么币种付的。
+这次会话折合多少人民币，取决于卖你额度那家给的汇率，而不是市场汇率——所以汇率是**配置**出来的，不是联网抓的。
+
+创建 `~/.pi/agent/statusline.json`：
+
+```json
+{
+  "currency": {
+    "code": "CNY",
+    "perUsd": 7.12
+  }
+}
+```
+
+- `code` 决定符号（`CNY` 与 `RMB` 得到 `¥`；符号表还认 `USD`、`EUR`、`GBP`、`JPY`、`HKD`、`TWD`、
+  `SGD`、`KRW`、`INR`）。表里没有的代码就原样打印。
+- `symbol` 可覆盖符号表，用于表里没列的币种，或想换分隔方式。
+- `perUsd` 是一美元等于多少该币种，也就是**你实际被收的汇率**。必须是正数；
+  否则整块被拒绝，footer 继续显示美元。
+
+配置成上面这样，同一个会话就从 `Cost $0.229` 变成 `Cost ¥1.63`。该文件每个会话只读一次，
+改完需 `/reload`。文件存在但不可用时会给出通知，而不是静默继续显示美元。
+
 ## 指标口径
 
 吞吐与延迟遵循 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 的 turn-metrics 契约

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

@@ -5,8 +5,8 @@
  *
  * Design notes:
  *
- * - Every value carries a word ("Context", "Cache", "Cost", "Effort"), not a symbol: icon-only labels
- *   are unreadable at a glance.
+ * - Every value carries a word ("Context", "Input", "Output", "Cache hit", "Cost", "Effort"), not a
+ *   symbol: icon-only labels are unreadable at a glance.
  * - Keys render dim and values render brighter, so a key/value pair reads as one unit instead of as a
  *   run of equal-weight tokens.
  * - The meter is a FIXED 20 cells and never stretches to the terminal, so it reads as an instrument
@@ -18,6 +18,9 @@
  * stepStartTime; decodeMs = completedTime - firstTokenTime; tok/s = usage.output / (decodeMs / 1000)
  */
 
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
 import type {
   ExtensionAPI,
   ExtensionContext,
@@ -26,18 +29,17 @@ import type {
 import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
 
 import {
-  bar,
-  BAR_CELLS,
-  formatCost,
+  contextRow,
+  currencyFromConfig,
   formatCwd,
   formatLatency,
-  formatTokens,
   formatTps,
   isQuietStatus,
   pair,
-  percentColor,
   row,
   shortenPath,
+  USD,
+  type Currency,
 } from './render.ts'
 
 const LIVE_RENDER_MS = 200
@@ -46,6 +48,23 @@ const MIN_SAMPLE_MS = 200
 /** 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')
+
+/**
+ * Reads the display currency.
+ *
+ * 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> {
+  const file = Bun.file(CONFIG_PATH)
+  const text = (await file.exists()) ? await file.text() : null
+  const { currency, problem } = currencyFromConfig(text)
+  if (problem !== null) notify(problem)
+  return currency
+}
+
 /** A content block as providers stream it; every field is read defensively. */
 type ContentBlock = {
   type?: unknown
@@ -148,6 +167,7 @@ function seedRatio(ctx: ExtensionContext): number | null {
 export default function (pi: ExtensionAPI) {
   let ratio: number | null = null
   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
@@ -184,31 +204,20 @@ export default function (pi: ExtensionAPI) {
         render(width: number): string[] {
           const usage = ctx.getContextUsage()
           const totals = collectTotals(ctx)
-          const percent = usage?.percent ?? null
-          const fraction = percent === null ? 0 : percent / 100
-
-          // Row 1 right: cache and cost, words instead of symbols.
-          const row1Parts: string[] = []
-          if (totals.cacheRead > 0)
-            row1Parts.push(pair(theme, 'Cache', formatTokens(totals.cacheRead)))
-          if (totals.cacheHitRate !== null) {
-            row1Parts.push(pair(theme, 'Hit', `${totals.cacheHitRate.toFixed(1)}%`))
-          }
-          if (totals.cost > 0) row1Parts.push(pair(theme, 'Cost', formatCost(totals.cost)))
-          const row1Right = row1Parts.join(theme.fg('dim', '  ·  '))
-
-          // Row 1 left: fixed-size meter, percentage as the hero, absolute figures
-          // as quiet secondary detail. Air to the right of the meter is deliberate.
-          const pctColor = percentColor(percent)
-          const pctText = theme.fg(pctColor, percent === null ? '?' : `${percent.toFixed(1)}%`)
-          const window = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0
-          const detail =
-            window > 0 ? `${formatTokens(usage?.tokens ?? 0)} / ${formatTokens(window)}` : ''
-          const meter = `${theme.fg('dim', 'Context')}  ${bar(theme, BAR_CELLS, fraction)}  ${pctText}`
-          const withDetail = detail ? `${meter}   ${theme.fg('dim', detail)}` : meter
-          // Shed the secondary detail before the cache/cost group gets squeezed.
-          const row1Left =
-            visibleWidth(withDetail) + 2 + visibleWidth(row1Right) <= width ? withDetail : meter
+          const row1 = contextRow(
+            theme,
+            width,
+            {
+              percent: usage?.percent ?? null,
+              tokens: usage?.tokens ?? 0,
+              window: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
+              input: totals.input,
+              output: totals.output,
+              cacheHitRate: totals.cacheHitRate,
+              cost: totals.cost,
+            },
+            currency,
+          )
 
           // Row 2: model and the latest turn's timing on the right, path on the left.
           const model = ctx.model?.id ?? 'no model'
@@ -245,10 +254,7 @@ export default function (pi: ExtensionAPI) {
           }
           const row2Left = pwdPlain ? theme.fg('muted', pwdPlain) : ''
 
-          const lines = [
-            row(theme, width, row1Left, row1Right),
-            row(theme, width, row2Left, row2Right),
-          ]
+          const lines = [row1, row(theme, width, row2Left, row2Right)]
 
           // Other extensions' status entries still belong on screen, minus the
           // ones that only report that nothing is happening.
@@ -269,6 +275,7 @@ export default function (pi: ExtensionAPI) {
     ratio = seedRatio(ctx)
     reading = null
     resetStream()
+    currency = await loadCurrency((message) => ctx.ui.notify(message, 'warning'))
     installFooter(ctx)
   })
 

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

@@ -1,9 +1,10 @@
 /**
  * Pure rendering helpers for the status line: number formatting, the context meter, the two-group
- * row layout, and the status-noise filter.
+ * row layout, the status-noise filter, and the display currency.
  *
  * Nothing here touches pi APIs, the filesystem, or the clock, so every export is a function of its
- * arguments alone and is covered by render.test.ts.
+ * arguments alone and is covered by render.test.ts. The config file is read by the caller and
+ * handed in as text, which is what keeps the parsing testable here.
  */
 
 import { homedir } from 'node:os'
@@ -79,9 +80,103 @@ export function formatCwd(cwd: string): string {
   }
 }
 
+/**
+ * A display currency: the symbol to print, and how many of its units one USD buys.
+ *
+ * Pi prices every model in USD and never names a unit — its own model type documents `cost` as
+ * "cost per million tokens" — so a conversion rate cannot be derived from pi and has to come from
+ * the person paying. What a session cost in RMB is set by whoever sold the credit, not by a market
+ * feed, which is why the rate is configured rather than fetched. See README.md for the file.
+ */
+export interface Currency {
+  symbol: string
+  perUsd: number
+}
+
+/** What the footer shows until the config file names something else. */
+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> = {
+  CNY: '¥',
+  EUR: '€',
+  GBP: '£',
+  HKD: 'HK$',
+  INR: '₹',
+  JPY: '¥',
+  KRW: '₩',
+  RMB: '¥',
+  SGD: 'S$',
+  TWD: 'NT$',
+  USD: '$',
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/**
+ * Validates a `currency` block.
+ *
+ * A rate that is missing, zero, negative or not a number is refused rather than defaulted: a
+ * confident wrong amount is worse than the unconverted one the caller falls back to.
+ *
+ * @param raw - The `currency` value from a parsed config file.
+ * @returns The currency, or null when the block could not be used.
+ */
+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 }
+}
+
+/** A currency, plus the message to show when the config named one that could not be used. */
+export interface CurrencyConfig {
+  currency: Currency
+  problem: string | null
+}
+
+/**
+ * The display currency a config file asks for.
+ *
+ * @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 }
+  let config: unknown
+  try {
+    config = JSON.parse(text)
+  } catch {
+    return { currency: USD, problem: 'statusline.json is not valid JSON, showing USD' }
+  }
+  if (!isRecord(config) || !Object.hasOwn(config, 'currency')) {
+    return { currency: USD, problem: null }
+  }
+  const currency = parseCurrency(config.currency)
+  if (currency === null) {
+    return {
+      currency: USD,
+      problem: 'statusline.json currency needs a positive perUsd, showing USD',
+    }
+  }
+  return { currency, problem: null }
+}
+
 /** Three decimals, with one trailing zero trimmed so `$0.380` renders as `$0.38`. */
-export function formatCost(cost: number): string {
-  return `$${cost.toFixed(3).replace(/0$/, '')}`
+/**
+ * Three decimals, with the padding zeros trimmed so `$0.380` renders as `$0.38`.
+ *
+ * All of them, not just one: a converted amount lands on `¥17.800` often enough that a single
+ * trailing zero would show up as `¥17.80` beside `¥2.706` and read as a different precision.
+ */
+export function formatCost(cost: number, currency: Currency = USD): string {
+  return `${currency.symbol}${(cost * currency.perUsd).toFixed(3).replace(/\.?0+$/, '')}`
 }
 
 /**
@@ -144,6 +239,67 @@ export function row(theme: Theme, width: number, left: string, right: string): s
   return truncateToWidth(keep, width, theme.fg('dim', '…'))
 }
 
+/** The row-1 figures, already totalled by the caller. */
+export interface ContextRowParts {
+  percent: number | null
+  tokens: number
+  window: number
+  input: number
+  output: number
+  cacheHitRate: number | null
+  cost: number
+}
+
+/**
+ * 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:
+ *
+ * 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).
+ *
+ * @param currency - Used for the cost; defaults to USD so the row renders without a config file.
+ */
+export function contextRow(
+  theme: Theme,
+  width: number,
+  parts: ContextRowParts,
+  currency: Currency = USD,
+): string {
+  const fraction = parts.percent === null ? 0 : parts.percent / 100
+  const percent = theme.fg(
+    percentColor(parts.percent),
+    parts.percent === null ? '?' : `${parts.percent.toFixed(1)}%`,
+  )
+  const meter = `${theme.fg('dim', 'Context')}  ${bar(theme, BAR_CELLS, fraction)}  ${percent}`
+  const detail =
+    parts.window > 0 ? `${formatTokens(parts.tokens)} / ${formatTokens(parts.window)}` : ''
+  const withDetail = detail === '' ? meter : `${meter}   ${theme.fg('dim', detail)}`
+
+  // Volume, then the numbers that describe what the session cost.
+  const volumes: string[] = []
+  if (parts.input > 0) volumes.push(pair(theme, 'Input', formatTokens(parts.input)))
+  if (parts.output > 0) volumes.push(pair(theme, 'Output', formatTokens(parts.output)))
+  const outcomes: string[] = []
+  if (parts.cacheHitRate !== null) {
+    outcomes.push(pair(theme, 'Cache hit', `${parts.cacheHitRate.toFixed(1)}%`))
+  }
+  if (parts.cost > 0) outcomes.push(pair(theme, 'Cost', formatCost(parts.cost, currency)))
+
+  const separator = theme.fg('dim', '  ·  ')
+  const full = [...volumes, ...outcomes].join(separator)
+  const core = outcomes.join(separator)
+  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)
+}
+
 /** `label value` where the key is quiet and the value is not. */
 export function pair(theme: Theme, key: string, value: string, color: ThemeColor = 'text'): string {
   return `${theme.fg('dim', key)} ${theme.fg(color, value)}`