pi-quota-dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mufeiyu-ayu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# pi-quota-dashboard
+
+**English** · [简体中文](./README.zh-CN.md)
+
+A read-only quota, balance and session dashboard for the [pi coding agent](https://pi.dev) — **Claude, OpenAI Codex and DeepSeek in a single footer line**.
+
+Every other pi extension covers either subscription windows (Anthropic OAuth, Codex) *or* API balance (DeepSeek). This one does both, because they are different billing concepts and a dashboard should not pretend otherwise.
+
+![The merged footer line](./docs/footer.png)
+
+That shot is a Codex Pro account: `7d 25% (4d9h)` is the single 7-day window it returns — no 5h, because Pro does not have one. The branch segment is absent because that session is not in a git repository. The quota segment on the other providers:
+
+```
+5h 98% (3h12m) · 7d 49% · Fable 13%   Claude — one entry per window
+(nothing)                             DeepSeek — a funded balance stays out of the way
+```
+
+Verified against **pi 0.85.1 / Node 22.20.0**.
+
+## What it does
+
+- **Shows remaining quota, not consumed** — you care about what is left.
+- **One line, not three.** pi's built-in footer takes three rows (cwd / stats / extension statuses). This collapses all of them into one.
+- **Only the windows your account actually has.** A Codex Pro account returns exactly one 7-day window — no 5h, no code-review bucket. Those are not invented as "unavailable" rows.
+- **Never writes credentials.** No auto-login, no token refresh, no writes to `auth.json`. An expired credential is reported as `expired` and left alone.
+- **Never claims more than it knows.** `activeAccountVerified` is permanently `false` — see [Honest by construction](#honest-by-construction).
+
+## Install
+
+```sh
+pi install git:github.com/mufeiyu-ayu/pi-quota-dashboard
+```
+
+Then run `/reload` in your pi session. No `npm install` needed — pi provides the dependencies.
+
+For local development, clone it and point pi at the directory:
+
+```sh
+git clone https://github.com/mufeiyu-ayu/pi-quota-dashboard.git
+pi install ./pi-quota-dashboard
+```
+
+## The footer line
+
+pi's built-in footer is three rows: working directory, stats, extension statuses. This extension uses `ui.setFooter()` to collapse all three into **one**, segments separated by `│`:
+
+```
+🤖 high · gpt-6-astra │ main │ ██░░░░░░░░ 18.5% 185k/1.0M │ $0.061 │ 7d 25% (4d11h)
+  └─── model ────┘   └branch┘  └──────── context ─────────┘  └─ cost ─┘  └── quota ──┘
+```
+
+Everything is left-aligned — nothing is pushed to the far right where it gets truncated first.
+
+- **Thinking level comes before the model name**, coloured with pi's own thinking scale (grey → blue → violet → magenta), so the strength reads at a glance.
+- **The provider is not shown.** `gpt-6-astra`, `deepseek-v4-flash` and `claude-fable-5-1` already say which vendor they are; the prefix cost 16 columns for nothing.
+- **Only the git branch, no working directory.** The branch is the part that changes and is worth watching; you already know which project you are in. Outside a repository the segment disappears entirely.
+
+### Context
+
+A 10-cell progress bar, the percentage, and the absolute count. Bar and number share a colour, using pi's own thresholds: **70% amber, 90% red**. Right after a compaction the percentage shows `?` until the next response — pi genuinely does not know yet, so nothing is guessed.
+
+### Quota
+
+| Element | Meaning |
+|---|---|
+| `25%` colour | Graded on **remaining**: >50% green, >20% amber, else red. Windows are separated by `·` |
+| `~` | Data is stale (not refreshed this cycle). Percentages also lose their colour — a colour scale only means something on freshly fetched data |
+| `5h` `7d` `1d` | Window length, derived from `durationSeconds`. Model-scoped weekly windows get the model name (`7d Opus`), `weekly_scoped` uses the service's own display name (`Fable`), Codex code-review buckets are prefixed `CR` |
+| `25%` | **Remaining**, not consumed |
+| `(4d11h)` | Reset countdown, shown only for the shortest window — it resets first and is the one you hit |
+| `¥0.00` (red) | API balance, shown **only when it runs dry** (the service reports `is_available:false`, or the amount truncates to zero/negative). A balance does not run out mid-session the way a quota does, so it stays out of the way. Full figures via `/dashboard` |
+| `…` / status word | Querying / could not fetch (`?`, `n/a`, `auth`, `expired`, `403`, `429`, `error`). Definite problems are red, merely-missing data stays dim. A healthy `ok` prints no status word at all |
+
+Windows with no data are **omitted entirely** rather than occupying a `?%` slot. If the active provider has no quota concept, the whole segment is withdrawn instead of leaving a gap.
+
+### Responsive degradation
+
+A narrow terminal must not push the quota — the whole point of the extension — off the end of the line. So segments are dropped by priority instead of truncating blindly:
+
+| Width | Shows |
+|---|---|
+| Wide | `🤖 high · model │ main │ ██░░░░░░░░ 18.5% 185k/1.0M │ $0.061 │ quota` |
+| Narrower | absolute token count dropped — the bar and the percentage already say it |
+| Narrower still | branch dropped |
+| Narrowest | the line is truncated from the right. Model, quota and other extension statuses are never dropped as segments |
+
+`setStatus()` is still published normally, so if another extension takes over the footer this one keeps showing up there. `session_shutdown` hands the built-in footer back.
+
+**Only this extension's own status is rendered.** pi normally lines up every extension's `setStatus()` output on a third row; this line replaces that row, so other status-publishing extensions have nowhere to show. A deliberate trade-off for a clean single line — if you rely on another statusline-style extension, this one will hide it.
+
+### Differences from the built-in footer
+
+These are extension-API boundaries, not preferences:
+
+| Item | Why |
+|---|---|
+| `(auto)` | **Not shown.** `autoCompactionEnabled` lives on pi's internal session object and is unreachable from `ExtensionContext`. Better absent than possibly stale |
+| provider prefix | **Not shown.** pi prints `(openai-codex)` when several providers are configured; the model id already identifies the vendor |
+| `(sub)` | Mirrors pi's `isUsingSubscription`, but the `snapshot.auth` map behind `isUsingOAuth` is unreachable, so it uses `readStoredCredential(id)?.type === 'oauth' && provider.auth.oauth.isSubscription`. OAuth from environment/runtime is missed — under-reporting beats guessing |
+| `↑↓RW` `CH` | **Not shown.** The per-direction token breakdown and cache-hit rate are covered by the cost and context segments; cumulative token counts remain in `/dashboard`. |
+| `$?` | pi prints the running total; this keeps the conservative reading — if a **billable** response reports a cost of 0, the figure is untrustworthy, so it says so. An all-zero empty response (an abort, a model switch) is self-consistent and does not poison the session |
+
+Everything else — context thresholds, truncation behaviour — matches the built-in footer.
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/dashboard` | Re-reads the stored/environment credential source and prints the full redacted JSON snapshot. Quota is reused within a 60s TTL |
+| `/dashboard refresh` | Bypasses the TTL — but **not** the failure backoff |
+
+Snapshots never enter the model's context and are never written to disk.
+
+## Honest by construction
+
+The reason this extension is worth reading: it is careful about what it claims.
+
+- **`activeAccountVerified` is always `false`.** The guards below reject visible overrides, but they cannot rule out a `before_provider_headers` hook silently swapping accounts, and on-disk config can differ from loaded config. So even a successful 200 is labelled as representing *the stored/environment account*, not a verified active request account. It never reads private runtime state or executes header hooks to guess.
+- **Subscription quota and API balance are strictly separate** (`kind`). An allowance and a balance are not interchangeable numbers.
+- **Balances stay decimal strings.** No float conversion, no currency conversion. The footer truncates to two places and appends `+` when it drops non-zero digits, so a tiny positive balance never renders as a flat `0.00`.
+- **Zero is not free.** pi initialises missing prices to zero; a billable response reporting `cost: 0` is reported as unknown rather than as a measured free call.
+- **Stale is not fresh.** A failed refresh keeps the previous `fetchedAt` and is marked `stale` — it is never relabelled as a successful fetch.
+
+### Credential handling
+
+- Reuses pi's exported `readStoredCredential` and the **stock** provider `oauth.toAuth` / DeepSeek `apiKey.resolve`. Never calls `getProviderAuth` / `getApiKeyAndHeaders`, which may refresh or write.
+- API keys accept a literal, or a single `$ENV` / `${ENV}` reference (provider-scoped env wins). `!command` credentials and compound templates are **never executed** — they report `unsupported`.
+- Runtime credential overrides, registered provider overrides, non-official `baseUrl`, visible headers, and per-provider auth config in `models.json` all fall back to `unsupported`.
+- Requests go to fixed official HTTPS paths only. Redirects are refused (`redirect: 'manual'`), the model's `baseUrl` is never used as a quota target, and tokens, headers, raw error bodies, account ids and fingerprints are never logged.
+
+### Endpoints
+
+| Provider | Endpoint | Auth |
+|---|---|---|
+| Claude | `GET https://api.anthropic.com/api/oauth/usage` | OAuth bearer + `anthropic-beta: oauth-2025-04-20` |
+| Codex | `GET https://chatgpt.com/backend-api/wham/usage` | OAuth bearer + `ChatGPT-Account-Id` |
+| DeepSeek | `GET https://api.deepseek.com/user/balance` | Bearer API key |
+
+Claude and Codex expose internal/unstable quota endpoints with no compatibility promise. DeepSeek follows its [documented balance API](https://api-docs.deepseek.com/api/get-user-balance).
+
+### Caching and lifecycle
+
+Cache is keyed by a SHA-256 fingerprint of provider + fixed endpoint + token + account (never emitted), so two accounts can never read each other's data. Concurrent requests for one key are coalesced, at most 16 entries. HTTP deadline 8s including the body, auth derivation 8s separately, response body capped at 256 KiB. Failures back off 60/120/240/300s and honour `Retry-After` (seconds or HTTP-date, capped at one day). 401/403/429 are never routed around.
+
+Refresh polls every 60s, and only in UI mode. Every publish path and async continuation independently re-checks provider/model/baseUrl identity, so a model switch cancels in-flight requests and discards late results rather than attributing them to the new model. Credentials are re-read after the HTTP call — if they changed mid-flight, the result is dropped instead of published against the wrong account. Cache is memory-only.
+
+## Provider support
+
+| Provider | Reported |
+|---|---|
+| `anthropic` | `five_hour`, `seven_day`, model-scoped weekly windows (`seven_day_opus`, `seven_day_sonnet`, `weekly_scoped`) |
+| `openai-codex` | `rate_limit` and `code_review_rate_limit` primary/secondary windows — whichever the account actually returns |
+| `deepseek` | Exact CNY/USD API balances as decimal strings |
+
+Any other provider reports `unsupported` and the segment is withdrawn.
+
+> **Note on Claude:** pi's docs state that third-party harness calls against a Claude subscription consume extra usage and are billed per token rather than against plan windows. The 5h/7d figures here are the account's plan allowance as returned by the official endpoint — **not a pi budget**. No `extra_usage` field or session cost estimate is mixed into the plan windows.
+
+## Development
+
+The npm package ships only the runtime files, so clone the repository to run the tests:
+
+```sh
+git clone https://github.com/mufeiyu-ayu/pi-quota-dashboard.git
+cd pi-quota-dashboard
+node --test test/*.test.mjs
+
+# prints usage only, no network
+node scripts/smoke.mjs
+
+# explicit, free, read-only real GET; prints redacted business fields and HTTP status, never credentials
+node scripts/smoke.mjs --live
+node scripts/smoke.mjs --live deepseek
+```
+
+All `FAKE_*` fixtures are simulated. Tests also cover the real installed extension loader, the stock auth functions against fake credentials, and both the built-in `FooterComponent` and this extension's merged footer at 0/1/2/3/8/20/40/80/160 columns — without starting the pi CLI or issuing a model request. The merged footer is rendered through the factory registered by pi's real extension loader, not by bypassing the load path.
+
+Standalone scripts locate pi from the current Node's global install directory; set `PI_DASHBOARD_PI_ROOT` for other layouts. Integration tests assert `pi.VERSION === '0.85.1'` — on a pi upgrade that assertion fails deliberately, as a prompt to re-check the auth, loader and footer APIs before bumping it.
+
+## Attribution
+
+Endpoint and response-field research for Claude and Codex referenced [claude-dashboard](https://github.com/uppinote20/claude-dashboard) by uppinote (MIT). This package implements its own credential handling, parsers, cache and lifecycle integration, and does not execute or redistribute that bundle. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,186 @@
+# pi-quota-dashboard
+
+[English](./README.md) · **简体中文**
+
+给 [pi coding agent](https://pi.dev) 的只读额度 / 余额 / 会话面板 —— **Claude、OpenAI Codex、DeepSeek 三家挤进底栏一行**。
+
+生态里其他扩展要么只查订阅窗口（Anthropic OAuth、Codex），要么只查 API 余额（DeepSeek）。这个两样都做，因为它们本来就是两种计费概念，面板不该把它们混成一个数字。
+
+![合并后的底栏](./docs/footer.png)
+
+这张图是 Codex Pro 账户：`7d 25% (4d9h)` 就是它返回的唯一一个 7 天窗口 —— 没有 5h，因为 Pro 本来就没有。分支段不在，是因为那个会话不在 git 仓库里。换成其他 provider 时，额度段会是：
+
+```
+5h 98% (3h12m) · 7d 49% · Fable 13%   Claude —— 一个窗口一条
+（什么都没有）                          DeepSeek —— 余额充足就不占位
+```
+
+验证版本 **pi 0.85.1 / Node 22.20.0**。
+
+## 特点
+
+- **显示剩余额度，不是已用** —— 关心的是还能用多少。
+- **一行，不是三行。** pi 内置 footer 占三行（工作目录 / 统计 / 扩展状态），这里全部并成一行。
+- **只显示账户真正有的窗口。** Codex Pro 账户只返回一个 7 天窗口，没有 5h、没有 code review 桶 —— 这些不会被凭空造成 "unavailable" 条目。
+- **绝不写凭据。** 不自动登录、不刷新 token、不写 `auth.json`。凭据过期就如实报 `expired`，不动它。
+- **不声称自己不知道的事。** `activeAccountVerified` 恒为 `false`，理由见[诚实是设计出来的](#诚实是设计出来的)。
+
+## 安装
+
+```sh
+pi install git:github.com/mufeiyu-ayu/pi-quota-dashboard
+```
+
+然后在 pi 会话里执行 `/reload`。无需 `npm install`，依赖由 pi 提供。
+
+本地开发：
+
+```sh
+git clone https://github.com/mufeiyu-ayu/pi-quota-dashboard.git
+pi install ./pi-quota-dashboard
+```
+
+## 底栏
+
+pi 内置 footer 占三行：工作目录、统计、扩展状态。本扩展用 `ui.setFooter()` 把三行全部并成**一行**，用 `│` 分段：
+
+```
+🤖 high · gpt-6-astra │ main │ ██░░░░░░░░ 18.5% 185k/1.0M │ $0.061 │ 7d 25% (4d11h)
+  └─── 模型 ────┘   └分支┘  └───────── 上下文 ────────┘  └─ 费用 ─┘  └── 额度 ──┘
+```
+
+整行左对齐 —— 没有任何东西被推到最右边、最先被截断的位置。
+
+- **思考强度排在模型名前面**，用 pi 自己的 thinking 分级色（灰 → 蓝 → 紫 → 品红），强度一眼可辨。
+- **不显示厂商。** `gpt-6-astra`、`deepseek-v4-flash`、`claude-fable-5-1` 本身就说明是哪一家，这个前缀白占 16 列。
+- **只显示 git 分支，不显示工作目录。** 分支才是会变、值得盯的那部分；自己在哪个项目你本来就知道。不在 git 仓库里时整段消失。
+
+### 上下文
+
+10 格进度条 + 百分比 + 绝对计数。条身与数字同色，阈值沿用 pi 的 **70% 黄 / 90% 红**。压缩之后到下一次响应之前，百分比显示 `?` —— pi 此时确实不知道，不猜。
+
+### 额度
+
+| 元素 | 含义 |
+|---|---|
+| `25%` 颜色 | 按**剩余**分档：>50% 绿 / >20% 黄 / 其余红。多个窗口之间用 `·` 分隔 |
+| `~` | 数据过期未刷新（stale），同时百分比不着色 —— 色阶只在当次刷新过的数据上才代表真实水位 |
+| `5h` `7d` `1d` | 窗口时长，从 `durationSeconds` 推导。模型专属周窗补模型名（`7d Opus`），`weekly_scoped` 用服务返回的显示名（`Fable`），Codex code review 桶前缀 `CR` |
+| `25%` | **剩余** 25%，不是已用 |
+| `(4d11h)` | 重置倒计时，只给最短的窗口显示 —— 它最先重置，也最常撞上 |
+| `¥0.00`（红） | API 余额**只在见底时**提示（服务报 `is_available:false`，或截断到 2 位后为零/负）。余额不像配额那样会在会话中途用光，平时不占位，完整数字看 `/dashboard` |
+| `…` / 状态词 | 查询中 / 取不到（`?`、`n/a`、`auth`、`expired`、`403`、`429`、`error`）。确定出问题的标红，只是取不到数的保持 dim。健康的 `ok` 不写状态词 |
+
+**没有数据的窗口整个略去**，不占一个 `?%` 的位置。当前 provider 没有额度概念时整条撤掉，不留空位。
+
+### 按宽度降级
+
+窄终端不该把额度 —— 这个扩展的主角 —— 挤出行外。所以是按优先级丢段，不是无脑截断：
+
+| 终端宽度 | 显示 |
+|---|---|
+| 宽 | `🤖 high · model │ main │ ██░░░░░░░░ 18.5% 185k/1.0M │ $0.061 │ 额度` |
+| 窄 | 丢绝对 token 计数 —— 进度条和百分比已经说明同一件事 |
+| 更窄 | 再丢分支 |
+| 最窄 | 整行从右侧截断。模型、额度和其他扩展状态不会作为整段被丢掉 |
+
+`setStatus()` 照常发布，所以别的扩展接管 footer 时本插件依然显示；`session_shutdown` 交还内置 footer。
+
+**只渲染本扩展自己的状态。** pi 原本把所有扩展的 `setStatus()` 内容排在第三行，这一行取代了它，因此其他会发布状态的扩展没有显示位置。这是为了单行整洁而有意做的取舍 —— 如果你依赖别的状态类扩展，它会被这一行盖掉。
+
+### 与内置 footer 的差异
+
+都是扩展 API 的边界所致，不是选择：
+
+| 项 | 说明 |
+|---|---|
+| `(auto)` | **不显示**。`autoCompactionEnabled` 只在 pi 内部的 session 对象上，`ExtensionContext` 拿不到。与其显示一个可能过期的标记，不如不显示 |
+| 厂商前缀 | **不显示**。配置了多个 provider 时 pi 会打印 `(openai-codex)`；模型 id 已经能说明是哪一家 |
+| `(sub)` | 与 pi 的 `isUsingSubscription` 同构，但 `isUsingOAuth` 依赖的 `snapshot.auth` 不可达，改用 `readStoredCredential(id)?.type === 'oauth' && provider.auth.oauth.isSubscription`。environment/runtime 的 OAuth 会漏标 —— 宁可漏也不猜 |
+| `↑↓RW` `CH` | **不显示**。分方向的 token 明细和缓存命中率已由费用段与上下文段覆盖；累计 token 数仍在 `/dashboard` 里 |
+| `$?` | pi 直接显示累加值；这里保持保守口径 —— **计费过的**响应报 cost=0 时这个数不可信，就明说。分项全为 0 的空响应（中断、切模型）零成本自洽，不会抹掉整轮会话 |
+
+其余（上下文着色阈值、截断行为）与内置 footer 一致。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/dashboard` | 重新读取存储/环境凭据来源，打印完整的脱敏 JSON 快照。额度在 60 秒 TTL 内复用 |
+| `/dashboard refresh` | 绕过正常 TTL，但**不绕过失败退避** |
+
+快照不进入模型上下文，也不落盘。
+
+## 诚实是设计出来的
+
+这个扩展值得一读的地方，在于它对"自己知道什么"很克制。
+
+- **`activeAccountVerified` 恒为 `false`。** 下面那些 guards 能挡住可见的覆盖，但挡不住 `before_provider_headers` 钩子悄悄换账户，磁盘配置也可能与已加载配置不同。所以即使拿到 200，也只标注为"代表*存储/环境账户*"，而非已验证的活动请求账户。不读私有 runtime，不执行 header hooks 去猜。
+- **订阅额度与 API 余额严格分开**（`kind`）。额度和余额不是可以互换的数字。
+- **余额保持十进制字符串。** 不做浮点换算，不换汇。底栏截断到 2 位，丢掉非零位时补 `+`，所以极小的正余额不会显示成干巴巴的 `0.00`。
+- **零不等于免费。** pi 会把缺失的价格初始化为零；计费过的响应报 `cost: 0` 时报 unknown，不当成实测的免费调用。
+- **过期不等于新鲜。** 刷新失败保留原来的 `fetchedAt` 并标 `stale`，绝不改头换面成一次成功刷新。
+
+### 凭据处理
+
+- 重用 pi 导出的 `readStoredCredential` 与**原装** provider `oauth.toAuth` / DeepSeek `apiKey.resolve`。绝不调用可能刷新/写入的 `getProviderAuth` / `getApiKeyAndHeaders`。
+- API key 支持明文，或单个 `$ENV` / `${ENV}` 引用（provider-scoped env 优先）。`!command` 凭据和复合模板**绝不执行**，直接报 `unsupported`。
+- runtime 临时凭据、已注册 provider 覆盖、非官方 `baseUrl`、可见 headers、`models.json` 里当前 provider/model 的鉴权配置，一律退回 `unsupported`。
+- 请求只进入固定的官方 HTTPS 路径。拒绝 redirect（`redirect: 'manual'`），不把模型的 `baseUrl` 当额度目标，不记录 token、headers、raw error body、账号或指纹。
+
+### 接口
+
+| Provider | 端点 | 鉴权 |
+|---|---|---|
+| Claude | `GET https://api.anthropic.com/api/oauth/usage` | OAuth bearer + `anthropic-beta: oauth-2025-04-20` |
+| Codex | `GET https://chatgpt.com/backend-api/wham/usage` | OAuth bearer + `ChatGPT-Account-Id` |
+| DeepSeek | `GET https://api.deepseek.com/user/balance` | Bearer API key |
+
+Claude 和 Codex 用的是官方服务的内部/非稳定额度接口，不承诺永久兼容。DeepSeek 依据其[官方余额文档](https://api-docs.deepseek.com/api/get-user-balance)。
+
+### 缓存与生命周期
+
+缓存按 provider + 固定端点 + token + account 的 SHA-256 指纹隔离（指纹不输出），两个账户永远读不到彼此的数据。同 key 的并发请求合并，最多 16 项。HTTP 8 秒含响应体，鉴权单独 8 秒，响应体上限 256 KiB。失败按 60/120/240/300 秒退避，支持 `Retry-After`（秒或 HTTP-date，上限一天）。401/403/429 不做任何绕路。
+
+仅 UI 模式下每 60 秒轮询。所有发布入口和异步结果都独立比对 provider/model/baseUrl 身份，模型切换会取消在途请求并丢弃迟到结果，而不是把它算到新模型头上。HTTP 调用后重读凭据 —— 期间变过就丢弃结果，不发布到错误的账户名下。缓存只在内存。
+
+## Provider 支持
+
+| Provider | 上报内容 |
+|---|---|
+| `anthropic` | `five_hour`、`seven_day`、模型专属周窗（`seven_day_opus`、`seven_day_sonnet`、`weekly_scoped`） |
+| `openai-codex` | `rate_limit` 与 `code_review_rate_limit` 的 primary/secondary 窗口 —— 账户实际返回哪些就是哪些 |
+| `deepseek` | 精确的 CNY/USD API 余额，十进制字符串 |
+
+其他 provider 报 `unsupported`，该段整条撤掉。
+
+> **关于 Claude：** pi 文档明确，第三方 harness 对 Claude 订阅的调用消耗 extra usage、按 token 计费，而不走计划窗口。这里的 5h/7d 是官方接口返回的账户计划额度，**不是 pi 的可用预算**。没有把 `extra_usage` 字段或会话估算成本混进计划窗口。
+
+## 开发
+
+npm 包只带运行时文件，跑测试请先 clone 仓库：
+
+```sh
+git clone https://github.com/mufeiyu-ayu/pi-quota-dashboard.git
+cd pi-quota-dashboard
+node --test test/*.test.mjs
+
+# 只打印用法，不联网
+node scripts/smoke.mjs
+
+# 显式、免费、只读的真实 GET；输出脱敏业务字段与 HTTP 状态，绝不输出凭据
+node scripts/smoke.mjs --live
+node scripts/smoke.mjs --live deepseek
+```
+
+测试中的 `FAKE_*` 均为模拟。另有真实 installed loader、原装 auth 函数（fake credential）、内置 `FooterComponent` 与本扩展合并 footer 各自在 0/1/2/3/8/20/40/80/160 列的检查 —— 不启动 pi CLI，不发模型请求。合并 footer 经 pi 真实扩展 loader 注册的 factory 渲染，不绕过加载链路。
+
+独立脚本默认从当前 Node 的全局安装目录定位 pi，其他布局可设 `PI_DASHBOARD_PI_ROOT`。集成测试断言 `pi.VERSION === '0.85.1'` —— pi 升级时这条会故意变红，提示先复核 auth、loader 和 footer API 再更新断言。
+
+## 署名
+
+Claude 与 Codex 的端点及响应字段研究参考了 uppinote 的 [claude-dashboard](https://github.com/uppinote20/claude-dashboard)（MIT）。本包自行实现凭据处理、解析、缓存与生命周期接入，不执行也不再分发该 bundle。详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。
+
+## 许可
+
+MIT

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Reference attribution
+
+Claude/Codex endpoint and response-field research used the locally installed
+**claude-dashboard 1.31.1** by **uppinote**, specifically `dist/index.js`
+(api-client and codex-client). This package independently implements its own
+strict read-only credential handling, parsers, cache and lifecycle integration;
+it does not execute or redistribute the dashboard bundle. The reference license
+is retained below.
+
+## claude-dashboard — MIT License
+
+Copyright (c) 2026 uppinote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Pi packages are imported from the user's existing installation, not vendored.
+Their own licenses remain with that installation.

package/auth.mjs

@@ -0,0 +1,122 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { ENDPOINTS, officialBase, unavailable, number } from './core.mjs';
+
+const secretString = (v) => typeof v === 'string' && v.length > 0 && v.length < 32768 && !/[\s\x00-\x1f\x7f]/.test(v);
+export function authFingerprint(provider, token, accountId = '') {
+  return createHash('sha256').update(JSON.stringify([provider, ENDPOINTS[provider], token, accountId])).digest('hex');
+}
+export function codexIdentity(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8'));
+    return { accountId: payload['https://api.openai.com/auth']?.chatgpt_account_id, expires: number(payload.exp) === null ? null : payload.exp * 1000 };
+  } catch { return {}; }
+}
+// Only plain literals and whole-variable references are accepted here. Never run
+// !commands (including keychain/CLI helpers) from a read-only status integration.
+export function readOnlyKey(raw, scoped = {}, env = process.env) {
+  if (raw === undefined) return { key: undefined };
+  if (typeof raw !== 'string' || raw.startsWith('!')) return { reason: 'command_or_invalid_credential' };
+  if (raw.includes('$')) {
+    const match = raw.match(/^\$(?:([A-Za-z_][A-Za-z0-9_]*)|\{([A-Za-z_][A-Za-z0-9_]*)\})$/);
+    if (!match) return { reason: 'credential_template_unsupported' };
+    const name = match[1] ?? match[2];
+    return { key: scoped[name] || env[name] || undefined, credentialSource: scoped[name] ? 'pi_scoped_environment' : 'environment' };
+  }
+  return { key: raw, credentialSource: 'pi_stored_api_key' };
+}
+
+// 与 pi 的 isUsingSubscription 同构（isUsingOAuth && provider.auth.oauth.isSubscription），
+// 但只认 Pi 存储的 OAuth：environment/runtime 凭据这一层看不到，宁可漏标 (sub) 也不猜。
+export function isSubscription(ctx, readCredential) {
+  const id = ctx.model?.provider;
+  if (id === undefined) return false;
+  if (id === 'kimi-coding') return true;
+  try {
+    return readCredential(id)?.type === 'oauth'
+      && ctx.modelRegistry.getProvider(id)?.auth?.oauth?.isSubscription === true;
+  } catch { return false; }
+}
+
+export function readModelConfig(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8').replace(/^\uFEFF/, '')); }
+  catch (error) { if (error?.code === 'ENOENT') return {}; throw new Error('configuration_unverified'); }
+}
+export function authConfigOverride(config, id, modelId) {
+  const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (!record(config) || (config.providers !== undefined && !record(config.providers))) return 'configuration_unverified';
+  const p = config.providers?.[id];
+  if (p === undefined) return null;
+  if (!record(p)) return 'configuration_unverified';
+  if (p.models !== undefined && !Array.isArray(p.models)) return 'configuration_unverified';
+  if (p.modelOverrides !== undefined && !record(p.modelOverrides)) return 'configuration_unverified';
+  const model = p.models?.find((m) => m?.id === modelId);
+  const override = p.modelOverrides?.[modelId];
+  const present = (v) => v !== undefined && v !== null && v !== '' && v !== false && !(record(v) && Object.keys(v).length === 0);
+  return [p.apiKey, p.headers, p.authHeader, p.oauth, model?.headers, override?.headers].some(present)
+    ? 'custom_auth_configuration_unconfirmed' : null;
+}
+
+// 仅解析 Pi 存储/环境凭据；公开配置检查不能排除已加载的隐藏 headers 或请求 hook，
+// 因此这些凭据始终不代表已验证的活动请求账户。
+export async function resolveCredential(ctx, { readCredential, providers, readConfig, env = process.env }, signal, now = Date.now()) {
+  const id = ctx.model?.provider;
+  let credentialSource = 'unresolved';
+  const fail = (state, reason) => ({ result: { ...unavailable(id, state, reason), credentialSource } });
+  if (!Object.hasOwn(ENDPOINTS, id ?? '')) return fail('unsupported', 'provider_not_supported');
+  const registry = ctx.modelRegistry;
+  const activeProvider = registry.getProvider(id);
+  if (!officialBase(id, ctx.model?.baseUrl) || !officialBase(id, activeProvider?.baseUrl))
+    return fail('unsupported', 'custom_endpoint');
+  if (registry.getRegisteredProviderConfig(id) || registry.getRegisteredNativeProvider(id) ||
+      Object.keys(ctx.model?.headers ?? {}).length || Object.keys(activeProvider?.headers ?? {}).length)
+    return fail('unsupported', 'custom_provider_or_headers');
+  try {
+    const configReason = authConfigOverride(readConfig(), id, ctx.model?.id);
+    if (configReason) return fail('unsupported', configReason);
+  } catch { return fail('unsupported', 'configuration_unverified'); }
+  const source = registry.getProviderAuthStatus(id)?.source;
+  if (source && !['stored', 'environment'].includes(source)) return fail('unsupported', 'auth_source_unconfirmed');
+  try {
+    signal.throwIfAborted();
+    const stored = readCredential(id);
+    const provider = providers[id];
+    let token, accountId;
+    if (id === 'deepseek') {
+      if (stored && stored.type !== 'api_key') return fail('unsupported', 'auth_type_unsupported');
+      const resolved = readOnlyKey(stored?.key, stored?.env, env);
+      if (resolved.reason) return fail('unsupported', resolved.reason);
+      credentialSource = resolved.key ? resolved.credentialSource : 'unresolved';
+      // 存储 key 无法解析时，不静默改用环境中的其他账户。
+      if (stored?.key !== undefined && !resolved.key) return fail('unauthenticated', 'credential_unresolved');
+      const auth = await provider.auth.apiKey.resolve({
+        credential: stored ? { type: 'api_key', key: resolved.key } : undefined,
+        ctx: { env: async (name) => {
+          const value = stored?.env?.[name] || env[name];
+          if (value) credentialSource = stored?.env?.[name] ? 'pi_scoped_environment' : 'environment';
+          return value;
+        }, fileExists: async () => false }, signal,
+      });
+      token = auth?.auth.apiKey;
+    } else {
+      if (!stored) return fail('unauthenticated', 'pi_oauth_missing');
+      if (stored.type !== 'oauth') return fail('unsupported', 'subscription_requires_pi_oauth');
+      credentialSource = 'pi_stored_oauth';
+      if (number(stored.expires) === null) return fail('unknown', 'credential_expiry_missing');
+      if (stored.expires <= now) return fail('expired', 'pi_oauth_expired_no_refresh');
+      token = (await provider.auth.oauth.toAuth(stored))?.apiKey;
+      if (id === 'openai-codex') {
+        const identity = codexIdentity(token ?? '');
+        accountId = identity.accountId;
+        if (!secretString(accountId)) return fail('unknown', 'account_id_missing');
+        if (identity.expires !== null && identity.expires !== undefined && identity.expires <= now)
+          return fail('expired', 'pi_oauth_expired_no_refresh');
+        if (stored.accountId && stored.accountId !== accountId) return fail('unknown', 'account_id_mismatch');
+      }
+    }
+    signal.throwIfAborted();
+    if (!token) return fail('unauthenticated', 'credential_missing');
+    if (!secretString(token)) return fail('error', 'credential_invalid');
+    return { provider: id, token, accountId, credentialSource, activeAccountVerified: false, key: authFingerprint(id, token, accountId) };
+  } catch { return fail(signal.aborted ? 'unavailable' : 'error', signal.aborted ? 'cancelled' : 'credential_resolution_failed'); }
+}

package/core.mjs

@@ -0,0 +1,208 @@
+export const TTL_MS = 60_000;
+// Core sorts status keys; keep common existing indicators first.
+export const STATUS_KEY = 'zz-pi-quota-dashboard';
+export const ENDPOINTS = Object.freeze({
+  anthropic: 'https://api.anthropic.com/api/oauth/usage',
+  'openai-codex': 'https://chatgpt.com/backend-api/wham/usage',
+  deepseek: 'https://api.deepseek.com/user/balance',
+});
+const BASES = {
+  anthropic: ['https://api.anthropic.com', 'https://api.anthropic.com/v1'],
+  'openai-codex': ['https://chatgpt.com/backend-api', 'https://chatgpt.com/backend-api/codex'],
+  deepseek: ['https://api.deepseek.com', 'https://api.deepseek.com/v1'],
+};
+export const number = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null;
+const percent = (v) => number(v) !== null && v <= 100 ? v : null;
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const safeLabel = (v) => typeof v === 'string' ? v.replace(/[\x00-\x1f\x7f-\x9f\u2028\u2029]/g, '').slice(0, 120) : null;
+const decimal = (v) => typeof v === 'string' && v.length <= 128 && /^-?\d+(?:\.\d+)?$/.test(v) ? v : null;
+const iso = (v) => typeof v === 'string' && /^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(v) && Number.isFinite(Date.parse(v)) ? new Date(v).toISOString() : null;
+const secondsISO = (v) => number(v) !== null && v <= 253402300799 ? new Date(v * 1000).toISOString() : null;
+export function officialBase(provider, baseUrl) {
+  return typeof baseUrl === 'string' && BASES[provider]?.includes(baseUrl.replace(/\/$/, '')) === true;
+}
+export function unavailable(provider, state, reason) {
+  return { provider: provider ?? null, kind: provider === 'deepseek' ? 'api_balance' : 'subscription_quota', credentialSource: 'unresolved', activeAccountVerified: false, state, reason, windows: [], balances: [] };
+}
+function window(id, raw, durationSeconds, isCodex = false, now = Date.now()) {
+  const usedPercent = percent(isCodex ? raw?.used_percent : raw?.utilization);
+  const resetAt = isCodex
+    ? secondsISO(raw?.reset_at) ?? (number(raw?.reset_after_seconds) !== null ? secondsISO(now / 1000 + raw.reset_after_seconds) : null)
+    : iso(raw?.resets_at);
+  return {
+    id, state: !object(raw) ? 'unavailable' : usedPercent === null ? 'unknown' : 'ok',
+    durationSeconds, usedPercent, remainingPercent: usedPercent === null ? null : 100 - usedPercent, resetAt,
+  };
+}
+export function parseQuota(provider, raw, now = Date.now()) {
+  if (!object(raw)) return unavailable(provider, 'error', 'invalid_response');
+  const result = unavailable(provider, 'unknown', 'fields_missing');
+  if (provider === 'anthropic') {
+    for (const id of ['five_hour', 'seven_day', 'seven_day_sonnet', 'seven_day_opus']) {
+      if (id === 'five_hour' || id === 'seven_day' || Object.hasOwn(raw, id))
+        result.windows.push(window(id, raw[id], id === 'five_hour' ? 18000 : 604800));
+    }
+    if (Array.isArray(raw.limits)) for (const item of raw.limits.slice(0, 30)) {
+      if (item?.kind === 'weekly_scoped') {
+        const scope = safeLabel(item.scope?.model?.display_name);
+        result.windows.push({ ...window('weekly_scoped', { utilization: item.percent, resets_at: item.resets_at }, 604800), scope });
+      }
+    }
+  } else if (provider === 'openai-codex') {
+    // 账户实际返回哪些窗口就是哪些：Pro 只有一个 7d 的 primary_window，
+    // 没有 5h secondary，也没有 code review 桶。缺席的窗口不凭空造成 unavailable。
+    for (const group of ['rate_limit', 'code_review_rate_limit']) {
+      if (!object(raw[group])) continue;
+      for (const id of ['primary_window', 'secondary_window']) {
+        if (!Object.hasOwn(raw[group], id)) continue;
+        const w = raw[group][id];
+        result.windows.push(window(`${group}.${id}`, w, number(w?.limit_window_seconds), true, now));
+      }
+    }
+  } else if (provider === 'deepseek') {
+    result.isAvailable = typeof raw.is_available === 'boolean' ? raw.is_available : null;
+    if (Array.isArray(raw.balance_infos)) result.balances = raw.balance_infos.slice(0, 30).map((b) => ({
+      currency: typeof b?.currency === 'string' && /^[A-Z]{3}$/.test(b.currency) ? b.currency : null,
+      total: decimal(b?.total_balance), granted: decimal(b?.granted_balance), toppedUp: decimal(b?.topped_up_balance),
+    }));
+    if (result.balances.some((b) => b.currency !== null && b.total !== null)) {
+      result.state = result.isAvailable === false ? 'unavailable' : 'ok';
+      result.reason = result.isAvailable === false ? 'balance_insufficient' : null;
+    }
+    return result;
+  } else return unavailable(provider, 'unsupported', 'provider_not_supported');
+  if (result.windows.some((w) => w.state === 'ok')) {
+    result.state = 'ok';
+    result.reason = null;
+  }
+  return result;
+}
+
+// Pi initializes missing provider usage/prices to zero. Keep the reported values,
+// but never call an all-zero response or an unpriced request a measured free call.
+export function sessionUsage(entries) {
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0 };
+  let count = 0, cost = 0, tokensKnown = true, costKnown = true;
+  const missing = new Set();
+  for (const e of entries) {
+    const assistant = e.type === 'message' && e.message?.role === 'assistant';
+    const usage = e.type === 'message' && ['assistant', 'toolResult'].includes(e.message?.role) ? e.message?.usage : ['compaction', 'branch_summary'].includes(e.type) ? e.usage : undefined;
+    if (!assistant && usage === undefined) continue;
+    count++;
+    let reported = 0;
+    for (const key of Object.keys(totals)) {
+      const value = number(usage?.[key]);
+      if (value === null) { tokensKnown = false; missing.add(key); }
+      else {
+        totals[key] += value;
+        if (key !== 'totalTokens') reported += value;
+      }
+    }
+    // 分项全为 0 是一次空响应（中断、切换模型），零 token 零成本自洽，不是缺数据。
+    // 只有计费过的响应报出 0 才可疑：那可能是 pi 的零价，不能当成实测的免费调用。
+    const empty = reported === 0;
+    if (assistant && !empty && !(number(usage?.totalTokens) > 0)) tokensKnown = false;
+    const value = number(usage?.cost?.total);
+    if (value === null || (value === 0 && !empty)) costKnown = false;
+    else cost += value;
+  }
+  return {
+    scope: 'all_entries_in_current_session', responsesWithUsage: count,
+    tokens: { state: tokensKnown ? (count ? 'reported' : 'known') : 'unknown', ...Object.fromEntries(Object.entries(totals).map(([key, value]) => [key, missing.has(key) ? null : value])), totalTokens: tokensKnown ? totals.totalTokens : null, reportedSubtotal: totals.totalTokens },
+    cost: { state: costKnown ? (count ? 'estimated' : 'known') : 'unknown', amount: costKnown ? cost : null, estimatedSubtotal: cost, currency: 'USD', source: 'pi_usage_cost_not_invoice' },
+  };
+}
+export function snapshot(ctx, quota) {
+  const usage = ctx.getContextUsage();
+  const tokens = number(usage?.tokens);
+  const entries = ctx.sessionManager.getEntries();
+  const last = entries.findLast((e) => e.type === 'message' && e.message?.role === 'assistant')?.message;
+  return {
+    lastResponse: last ? { provider: safeLabel(last.provider), requestedModel: safeLabel(last.model), returnedModel: safeLabel(last.responseModel) } : null,
+    model: { provider: safeLabel(ctx.model?.provider), id: safeLabel(ctx.model?.id), name: safeLabel(ctx.model?.name), thinking: safeLabel(ctx.thinkingLevel) },
+    context: { state: tokens === null ? 'unknown' : 'estimated', tokens, windowTokens: number(usage?.contextWindow ?? ctx.model?.contextWindow), usedPercent: tokens === null ? null : number(usage?.percent), source: 'pi_getContextUsage' },
+    session: sessionUsage(entries),
+    quota: { ...quota, credentialSource: quota.credentialSource ?? 'unresolved', activeAccountVerified: false },
+  };
+}
+// pi-tui 的 visibleWidth/truncateToWidth 按可见宽度计算，SGR 序列不占列也不会被截断切坏。
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const HEAT = ['\x1b[32m', '\x1b[33m', '\x1b[31m'];
+const paint = (code, text) => `${code}${text}${RESET}`;
+const dim = (text) => paint(DIM, text);
+// 分档看的是剩余量：还剩一半以上宽裕，两成以下告急。
+const level = (remainingPercent) => remainingPercent > 50 ? 0 : remainingPercent > 20 ? 1 : 2;
+const CURRENCY = { USD: '$', CNY: '¥', EUR: '€', GBP: '£', JPY: '¥' };
+const STATE_LABEL = {
+  unknown: '?', unavailable: 'n/a', unauthenticated: 'auth',
+  expired: 'expired', forbidden: '403', rate_limited: '429', error: 'error',
+};
+// 确定出了问题的状态标红；只是取不到数的保持 dim，不虚张声势。
+const PROBLEM = new Set(['unauthenticated', 'expired', 'forbidden', 'rate_limited', 'error']);
+const shortDuration = (seconds) => seconds === null ? null
+  : seconds % 86400 === 0 ? `${seconds / 86400}d`
+  : seconds % 3600 === 0 ? `${seconds / 3600}h`
+  : seconds % 60 === 0 ? `${seconds / 60}m` : `${seconds}s`;
+// 只保留两个最大单位：底栏宽度有限，宁可少写一位也不撑长这一行。
+function countdown(resetAt, now) {
+  const ms = Date.parse(resetAt ?? '') - now;
+  if (!Number.isFinite(ms) || ms <= 0) return null;
+  const minutes = Math.floor(ms / 60_000), hours = Math.floor(minutes / 60), days = Math.floor(hours / 24);
+  return days ? `${days}d${hours % 24}h` : hours ? `${hours}h${minutes % 60}m` : `${minutes}m`;
+}
+// 窗口时长本身就是最短的标签；模型专属周窗和 code review 桶各自补一个限定词区分。
+function windowLabel(w) {
+  if (w.scope) return w.scope;
+  const model = /^seven_day_(.+)$/.exec(w.id)?.[1];
+  const fallback = w.id.includes('secondary') ? '2nd' : w.id.includes('primary') ? '1st' : w.id;
+  return [
+    w.id.startsWith('code_review_') ? 'CR' : null,
+    shortDuration(w.durationSeconds) ?? fallback,
+    model ? model[0].toUpperCase() + model.slice(1) : null,
+  ].filter(Boolean).join(' ');
+}
+// 服务返回的十进制字符串按位截断，不做浮点换算，也不四舍五入抬高余额。
+// 截断掉的非零位补 `+`，免得极小的正余额在底栏显示成 0.00。
+const shortAmount = (value) => {
+  const [int, frac] = value.split('.');
+  if (frac === undefined) return int;
+  return `${int}.${frac.slice(0, 2)}${/[1-9]/.test(frac.slice(2)) ? '+' : ''}`;
+};
+export function statusText(s, now = Date.now()) {
+  const q = s.quota;
+  // 模型、思考级别、上下文、会话 tokens 和费用由 pi 自带 footer 显示，这里只补它没有的额度。
+  // 底栏不写插件名、凭据来源、账户核验提示和厂商；这些字段完整保留在 /dashboard 的快照里。
+  if (q.state === 'unsupported') return '';
+  if (q.state === 'loading') return dim('…');
+  // 数据过期未刷新时百分比不着色并缀 ~：色阶只在当次刷新过的数据上才代表真实水位。
+  const stale = q.state === 'stale';
+  const parts = [];
+  // 服务直接说余额不足时以它为准，不靠数字自行判断。
+  const insufficient = q.isAvailable === false;
+  if (q.kind === 'api_balance') for (const b of q.balances) {
+    // 余额不像配额那样会在会话中途用光，平时不占位；见底了才提示，完整数字在 /dashboard。
+    // 色阶与判空都按底栏实际显示的位数，所见即所得。
+    if (b.total === null) continue;
+    const short = shortAmount(b.total);
+    if (!insufficient && !/^-|^0+(?:\.0*)?$/.test(short)) continue;
+    const symbol = b.currency === null ? '' : CURRENCY[b.currency] ?? '';
+    const suffix = symbol === '' && b.currency !== null ? ` ${b.currency}` : '';
+    parts.push(paint(stale ? DIM : HEAT[2], `${symbol}${short}${suffix}`));
+  } else {
+    // 显示的是剩余额度，不是已用：关心的是还能用多少。
+    const shown = q.windows.filter((w) => w.remainingPercent !== null);
+    // 只给最短的窗口带重置倒计时：它最先重置，也最常撞上。
+    const shortest = Math.min(...shown.map((w) => w.durationSeconds ?? Infinity));
+    for (const w of shown) {
+      const rank = level(w.remainingPercent);
+      const left = w.durationSeconds === shortest ? countdown(w.resetAt, now) : null;
+      parts.push(`${dim(windowLabel(w))} ${paint(stale ? DIM : HEAT[rank], `${Math.round(w.remainingPercent)}%`)}${left ? dim(` (${left})`) : ''}`);
+    }
+  }
+  // 窗口之间用 · 分隔，与 footer 段落间的 │ 区分层级。
+  if (parts.length) return parts.join(dim(' · ')) + (stale ? dim(' ~') : '');
+  // 查到了数据但没有需要提示的（余额充足、窗口全无数据）：不占位，也不报警。
+  if (q.state === 'ok' || q.state === 'stale') return '';
+  return paint(PROBLEM.has(q.state) ? HEAT[2] : DIM, STATE_LABEL[q.state] ?? q.state);
+}

package/footer.mjs

@@ -0,0 +1,92 @@
+import { visibleWidth, truncateToWidth } from '@earendil-works/pi-tui';
+import { sessionUsage, STATUS_KEY } from './core.mjs';
+import { isSubscription } from './auth.mjs';
+
+// 口径对齐 pi core 的 footer（dist/modes/interactive/components/footer.js）。
+// 接管 footer 只为把扩展状态并进统计行；保留的显示尽量与内置一致，pi 升级时由
+// 集成测试的版本断言提示复核。两处有意不同：拿不到 autoCompactionEnabled，
+// 不显示 (auto)；token 明细（↑↓RW/CH）已由费用和上下文段覆盖，不再复刻。
+export const formatTokens = (count) =>
+  count < 1000 ? `${count}`
+  : count < 10_000 ? `${(count / 1000).toFixed(1)}k`
+  : count < 1_000_000 ? `${Math.round(count / 1000)}k`
+  : count < 10_000_000 ? `${(count / 1_000_000).toFixed(1)}M`
+  : `${Math.round(count / 1_000_000)}M`;
+
+const sanitize = (text) => text.replace(/[\r\n\t]/g, ' ').replace(/ +/g, ' ').trim();
+const MODEL_ICON = '🤖';
+const BAR_WIDTH = 10;
+const BAR_FILLED = '█';
+const BAR_EMPTY = '░';
+// 用 pi 自己的 thinking 分级色（灰→蓝→紫→品红），强度一眼可辨且与 pi 其余界面一致。
+// thinkingMax 在主题里是可选色，退回 Xhigh 以免主题没定义时取不到。
+const THINKING_COLOR = {
+  off: 'thinkingOff', minimal: 'thinkingMinimal', low: 'thinkingLow', medium: 'thinkingMedium',
+  high: 'thinkingHigh', xhigh: 'thinkingXhigh', max: 'thinkingMax',
+};
+
+export class MergedFooter {
+  constructor(theme, footerData, getContext, readCredential) {
+    Object.assign(this, { theme, footerData, getContext, readCredential });
+  }
+  // 进度条 + 百分比 + 计数，阈值沿用 pi 的 70/90。条身与数字同色，空槽走边框色。
+  contextSegment(ctx, withCounts = true) {
+    const usage = ctx.getContextUsage();
+    const windowTokens = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0;
+    const percent = usage?.percent ?? null;
+    const tokens = usage?.tokens ?? null;
+    const level = percent === null ? 'muted' : percent > 90 ? 'error' : percent > 70 ? 'warning' : 'success';
+    const filled = percent === null ? 0 : Math.round(Math.min(100, Math.max(0, percent)) / 100 * BAR_WIDTH);
+    const bar = (filled ? this.theme.fg(level, BAR_FILLED.repeat(filled)) : '')
+      + (filled < BAR_WIDTH ? this.theme.fg('borderMuted', BAR_EMPTY.repeat(BAR_WIDTH - filled)) : '');
+    const pct = this.theme.fg(level, percent === null ? '?' : `${percent.toFixed(1)}%`);
+    if (!withCounts) return `${bar} ${pct}`;
+    const counts = `${tokens === null ? '?' : formatTokens(tokens)}/${formatTokens(windowTokens)}`;
+    return `${bar} ${pct} ${this.theme.fg('dim', counts)}`;
+  }
+  // 思考强度在前、模型名在后；不显示厂商，模型 id 本身已经说明是哪一家。
+  modelSegment(ctx) {
+    const name = this.theme.fg('dim', ctx.model?.id ?? 'no-model');
+    if (!ctx.model?.reasoning) return name;
+    const level = ctx.thinkingLevel || 'off';
+    const color = THINKING_COLOR[level] ?? 'thinkingXhigh';
+    return `${this.theme.fg(color, level)}${this.theme.fg('borderMuted', ' · ')}${name}`;
+  }
+  render(width) {
+    const ctx = this.getContext();
+    if (!ctx || width <= 0) return [];
+    const dim = (text) => this.theme.fg('dim', text);
+    const usage = sessionUsage(ctx.sessionManager.getEntries());
+
+    // 工作目录里唯一会变、值得盯的是分支；目录名自己知道，不占列。
+    // 不在 git 仓库里就整段消失。
+    const branch = this.footerData.getGitBranch();
+    const subscription = isSubscription(ctx, this.readCredential);
+    const cost = usage.cost.amount;
+    // 费用未知时显示 $?，不拿 0 冒充已知的零花费。
+    const costText = cost || subscription || usage.cost.state === 'unknown'
+      ? `$${cost === null ? '?' : cost.toFixed(3)}${subscription ? ' (sub)' : ''}` : null;
+
+    // 只取本扩展自己的状态。pi 原本把所有扩展的 setStatus 内容排在第三行，
+    // 这一行取代了它，因此其他扩展的状态不会出现在这里 —— 是有意的取舍，
+    // 代价是同时装了别的状态类扩展时，它们没有显示位置。
+    const quota = sanitize(this.footerData.getExtensionStatuses().get(STATUS_KEY) ?? '');
+    // 放不下就逐级降级：先丢上下文的绝对计数（进度条和百分比已经说明了同一件事），
+    // 再丢分支。额度是这一行的主角，任何一级都不丢。
+    // 段落靠 │ 分隔，只有模型段带图标。
+    const separator = this.theme.fg('borderMuted', ' │ ');
+    const compose = (level) => {
+      const groups = [`${MODEL_ICON} ${this.modelSegment(ctx)}`];
+      if (level < 2 && branch) groups.push(dim(branch));
+      groups.push(this.contextSegment(ctx, level < 1));
+      if (costText) groups.push(this.theme.fg('warning', costText));
+      if (quota) groups.push(quota);
+      return groups.join(separator);
+    };
+
+    // 单行、左对齐：pi 内置 footer 的三行全部并进这一行，模型不再右对齐。
+    let line = compose(0);
+    for (let level = 1; level <= 2 && visibleWidth(line) > width; level++) line = compose(level);
+    return [truncateToWidth(line, width, dim('…'))];
+  }
+}

package/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { getAgentDir, readStoredCredential } from '@earendil-works/pi-coding-agent';
+import { join } from 'node:path';
+import { readModelConfig } from './auth.mjs';
+import { builtinProviders } from '@earendil-works/pi-ai/providers/all';
+import { Dashboard, registerDashboard } from './runtime.mjs';
+import { MergedFooter } from './footer.mjs';
+
+export default function (pi: ExtensionAPI) {
+  registerDashboard(pi, new Dashboard({
+    readCredential: readStoredCredential,
+    readConfig: () => readModelConfig(join(getAgentDir(), 'models.json')),
+    providers: Object.fromEntries(builtinProviders()
+      .filter((provider) => ['anthropic', 'openai-codex', 'deepseek'].includes(provider.id))
+      .map((provider) => [provider.id, provider])),
+  }, { createFooter: (...args) => new MergedFooter(...args) }));
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "pi-quota-dashboard",
+  "version": "0.1.0",
+  "description": "Read-only provider quota, balance and session dashboard for the pi coding agent — Claude, OpenAI Codex and DeepSeek in one footer line",
+  "keywords": ["pi-package", "pi-extension", "pi", "quota", "usage", "statusline", "footer", "anthropic", "openai-codex", "deepseek"],
+  "license": "MIT",
+  "author": "mufeiyu-ayu",
+  "repository": { "type": "git", "url": "git+https://github.com/mufeiyu-ayu/pi-quota-dashboard.git" },
+  "bugs": { "url": "https://github.com/mufeiyu-ayu/pi-quota-dashboard/issues" },
+  "homepage": "https://github.com/mufeiyu-ayu/pi-quota-dashboard#readme",
+  "type": "module",
+  "files": ["index.ts", "*.mjs", "docs", "THIRD_PARTY_NOTICES.md"],
+  "engines": { "node": ">=22.19.0" },
+  "pi": { "extensions": ["./index.ts"] },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "smoke": "node scripts/smoke.mjs"
+  }
+}

package/quota.mjs

@@ -0,0 +1,112 @@
+import { ENDPOINTS, TTL_MS, parseQuota, unavailable } from './core.mjs';
+
+export function retryAfterMs(value, now) {
+  if (typeof value !== 'string') return 0;
+  const seconds = /^\d+(?:\.\d+)?$/.test(value) ? Number(value) : null;
+  const ms = seconds === null ? Date.parse(value) - now : seconds * 1000;
+  return Number.isFinite(ms) ? Math.max(0, Math.min(ms, 86400_000)) : 0;
+}
+// A fixed endpoint per adapter; no caller URL and no redirect-following path.
+export async function requestQuota(auth, signal, fetcher = fetch, now = Date.now) {
+  const url = ENDPOINTS[auth.provider];
+  if (!Object.hasOwn(ENDPOINTS, auth.provider)) return unavailable(auth.provider, 'unsupported', 'provider_not_supported');
+  const headers = { Accept: 'application/json', Authorization: `Bearer ${auth.token}` };
+  if (auth.provider === 'anthropic') headers['anthropic-beta'] = 'oauth-2025-04-20';
+  if (auth.provider === 'openai-codex') headers['ChatGPT-Account-Id'] = auth.accountId;
+  const response = await fetcher(url, { method: 'GET', headers, redirect: 'manual', signal });
+  if (!response.ok) {
+    await response.body?.cancel().catch(() => {});
+    const state = response.status === 401 ? 'unauthenticated' : response.status === 403 ? 'forbidden' : response.status === 429 ? 'rate_limited' : 'error';
+    return { ...unavailable(auth.provider, state, response.status >= 300 && response.status < 400 ? 'redirect_blocked' : 'http_error'), httpStatus: response.status, retryAfterMs: retryAfterMs(response.headers.get('retry-after'), now()) };
+  }
+  // Bound untrusted responses; timeout stays active through body consumption.
+  if (!response.body) return unavailable(auth.provider, 'error', 'invalid_response');
+  const reader = response.body.getReader();
+  const cancelBody = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', cancelBody, { once: true });
+  if (signal.aborted) cancelBody();
+  const chunks = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 256 * 1024) {
+        await reader.cancel();
+        return unavailable(auth.provider, 'error', 'response_too_large');
+      }
+      chunks.push(value);
+    }
+    return { ...parseQuota(auth.provider, JSON.parse(Buffer.concat(chunks).toString('utf8')), now()), httpStatus: response.status };
+  } catch {
+    return unavailable(auth.provider, 'error', signal.aborted ? 'timeout_or_cancelled' : 'invalid_response');
+  } finally {
+    signal.removeEventListener('abort', cancelBody);
+    reader.releaseLock();
+  }
+}
+
+export class QuotaCache {
+  constructor({ fetcher = fetch, now = Date.now, timeoutMs = 8000, ttlMs = TTL_MS } = {}) {
+    Object.assign(this, { fetcher, now, timeoutMs, ttlMs });
+    this.entries = new Map();
+    this.pending = new Map();
+    this.epoch = 0;
+  }
+  view(key) {
+    const e = this.entries.get(key);
+    if (!e) return undefined;
+    const stale = e.result.fetchedAt !== undefined && this.now() - e.result.fetchedAt >= this.ttlMs;
+    return stale ? { ...e.result, state: 'stale' } : e.result;
+  }
+  async get(auth, force = false) {
+    const existing = this.pending.get(auth.key);
+    if (existing) return { ...await existing.promise, credentialSource: auth.credentialSource ?? 'unresolved', activeAccountVerified: false };
+    const e = this.entries.get(auth.key);
+    if (e && (this.now() < e.retryAt || (!force && this.now() < e.expiresAt)))
+      return { ...this.view(auth.key), credentialSource: auth.credentialSource ?? 'unresolved', activeAccountVerified: false };
+    const controller = new AbortController();
+    const epoch = this.epoch;
+    let timer;
+    const aborted = new Promise((resolve) => {
+      controller.signal.addEventListener('abort', () => resolve(unavailable(auth.provider, 'error', 'timeout_or_cancelled')), { once: true });
+      timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    });
+    const promise = (async () => {
+      let result = await Promise.race([
+        requestQuota(auth, controller.signal, this.fetcher, this.now).catch(() => unavailable(auth.provider, 'error', 'network_error')),
+        aborted,
+      ]);
+      const now = this.now();
+      const failed = !['ok', 'unknown', 'unavailable'].includes(result.state);
+      const failures = failed ? (e?.failures ?? 0) + 1 : 0;
+      const backoff = failed ? Math.max(result.retryAfterMs ?? 0, Math.min(300_000, this.ttlMs * 2 ** Math.min(failures - 1, 4))) : 0;
+      // 仅复用同一存储/环境凭据指纹的数据，不把失败刷新标成新数据。
+      if (!failed && result.httpStatus === 200) result = { ...result, fetchedAt: now };
+      else if (e?.result.fetchedAt !== undefined) result = {
+        ...e.result, state: 'stale', reason: result.reason, lastError: result.state, httpStatus: result.httpStatus ?? null,
+      };
+      result = { ...result, credentialSource: auth.credentialSource ?? 'unresolved', activeAccountVerified: false, checkedAt: now, retryAt: backoff ? now + backoff : null };
+      if (epoch === this.epoch) {
+        if (this.entries.size >= 16 && !this.entries.has(auth.key)) this.entries.delete(this.entries.keys().next().value);
+        this.entries.set(auth.key, { result, failures, retryAt: now + backoff, expiresAt: now + this.ttlMs });
+      }
+      return result;
+    })().finally(() => {
+      clearTimeout(timer);
+      if (this.pending.get(auth.key)?.promise === promise) this.pending.delete(auth.key);
+    });
+    this.pending.set(auth.key, { promise, controller });
+    return promise;
+  }
+  cancelPending() {
+    this.epoch++;
+    for (const p of this.pending.values()) p.controller.abort();
+    this.pending.clear();
+  }
+  clear() {
+    this.cancelPending();
+    this.entries.clear();
+  }
+}

package/runtime.mjs

@@ -0,0 +1,179 @@
+import { TTL_MS, STATUS_KEY, snapshot, statusText, unavailable } from './core.mjs';
+import { resolveCredential } from './auth.mjs';
+import { QuotaCache } from './quota.mjs';
+
+export { STATUS_KEY };
+const modelIdentity = (ctx) => {
+  const model = ctx.model;
+  return JSON.stringify([model?.provider, model?.id, model?.baseUrl]);
+};
+export class Dashboard {
+  constructor(authDeps, { cache = new QuotaCache(), setIntervalFn = setInterval, clearIntervalFn = clearInterval, now = Date.now, createFooter } = {}) {
+    Object.assign(this, { authDeps, cache, setIntervalFn, clearIntervalFn, now, createFooter });
+    this.generation = 0;
+    this.refreshId = 0;
+    this.quota = unavailable(null, 'unavailable', 'session_not_started');
+    this.authControllers = new Set();
+  }
+  start(ctx) {
+    this.stop();
+    this.ctx = ctx;
+    this.quota = unavailable(ctx.model?.provider, 'loading', null);
+    this.local(ctx);
+    if (ctx.hasUI) {
+      // 接管 footer 只为把扩展状态行并进统计行；状态仍照常经 setStatus 发布，
+      // 这样别的扩展接管 footer 时本插件依然显示。footer 由接线层注入，
+      // 使本模块不依赖 pi-tui。
+      if (this.createFooter && ctx.ui.setFooter) {
+        ctx.ui.setFooter((_tui, theme, footerData) =>
+          this.createFooter(theme, footerData, () => this.ctx, this.authDeps.readCredential));
+        this.footerOwned = true;
+      }
+      this.timer = this.setIntervalFn(() => { void this.refresh(); }, TTL_MS);
+      this.timer?.unref?.();
+      void this.refresh();
+    }
+  }
+  select(ctx) {
+    this.local(ctx);
+    if (ctx.hasUI) void this.refresh();
+  }
+  local(ctx = this.ctx) {
+    if (!this.ctx || !ctx) return;
+    this.ctx = ctx;
+    const identity = modelIdentity(ctx);
+    // ctx.model 是实时 getter，thinking 事件可能先于 model_select；每个发布入口独立检查。
+    if (identity !== this.modelIdentity) {
+      this.modelIdentity = identity;
+      this.generation++;
+      this.refreshId++;
+      this.cache.cancelPending();
+      for (const controller of this.authControllers) controller.abort();
+      this.key = undefined;
+      this.quota = unavailable(ctx.model?.provider, 'loading', 'model_changed');
+    }
+    // 仅发布已重读核对存储/环境凭据的数据，不表示验证了活动请求账户。
+    // cache 内的新响应可能仍在等待这次重读，不能直接取来显示。
+    if (this.quota.fetchedAt !== undefined && this.now() - this.quota.fetchedAt >= TTL_MS)
+      this.quota = { ...this.quota, state: 'stale' };
+    const s = snapshot(ctx, this.quota);
+    // 当前 provider 查不到额度时整条撤掉，不在底栏留一个空位。
+    if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, statusText(s) || undefined);
+    return s;
+  }
+  async refresh(force = false) {
+    const ctx = this.ctx;
+    if (!ctx) return;
+    this.local(ctx);
+    const identity = this.modelIdentity;
+    const generation = this.generation;
+    const refreshId = ++this.refreshId;
+    const current = () => {
+      if (!this.ctx) return false;
+      // 即便没有任何事件先到，也不能让实时 getter 的新模型接收旧请求结果。
+      if (modelIdentity(this.ctx) !== identity) { this.local(); return false; }
+      return generation === this.generation && refreshId === this.refreshId;
+    };
+    const controller = new AbortController();
+    this.authControllers.add(controller);
+    // Bound each auth derivation, separately from the HTTP deadline.
+    const resolve = async () => {
+      const timer = setTimeout(() => controller.abort(), 8000);
+      let onAbort;
+      try {
+        return await Promise.race([
+          resolveCredential(ctx, this.authDeps, controller.signal, this.now()),
+          new Promise((done) => {
+            onAbort = () => done({ result: unavailable(ctx.model?.provider, 'error', 'auth_timeout_or_cancelled') });
+            if (controller.signal.aborted) onAbort();
+            else controller.signal.addEventListener('abort', onAbort, { once: true });
+          }),
+        ]);
+      } finally {
+        clearTimeout(timer);
+        controller.signal.removeEventListener('abort', onAbort);
+      }
+    };
+    try {
+      const auth = await resolve();
+      if (!current()) return;
+      if (auth.result) {
+        this.key = undefined;
+        this.cache.cancelPending();
+        this.quota = auth.result;
+        return this.local();
+      }
+      if (this.key !== auth.key) {
+        this.key = auth.key;
+        this.quota = { ...unavailable(auth.provider, 'loading', null), credentialSource: auth.credentialSource };
+      }
+      this.local();
+      const result = await this.cache.get(auth, force);
+      if (!current()) return;
+      // 请求期间存储/环境凭据可能改变；重读只核对该来源，不执行或推断请求 header hook。
+      const confirmed = await resolve();
+      if (!current()) return;
+      if (confirmed.result || confirmed.key !== auth.key || confirmed.credentialSource !== auth.credentialSource) {
+        this.key = undefined;
+        this.cache.cancelPending();
+        this.quota = confirmed.result ?? unavailable(auth.provider, 'unavailable', 'account_changed_refresh_required');
+      } else this.quota = result;
+      return this.local();
+    } catch {
+      if (current()) {
+        this.key = undefined;
+        this.quota = unavailable(ctx.model?.provider, 'error', 'dashboard_refresh_failed');
+        return this.local();
+      }
+    } finally {
+      this.authControllers.delete(controller);
+    }
+  }
+  stop() {
+    this.generation++;
+    this.refreshId++;
+    if (this.timer !== undefined) this.clearIntervalFn(this.timer);
+    this.timer = undefined;
+    for (const controller of this.authControllers) controller.abort();
+    this.authControllers.clear();
+    this.cache.clear();
+    if (this.ctx?.hasUI) {
+      this.ctx.ui.setStatus(STATUS_KEY, undefined);
+      if (this.footerOwned) this.ctx.ui.setFooter?.(undefined); // 交还内置 footer
+    }
+    this.footerOwned = false;
+    this.ctx = undefined;
+    this.modelIdentity = undefined;
+    this.key = undefined;
+    this.quota = unavailable(null, 'unavailable', 'session_stopped');
+  }
+}
+export function registerDashboard(pi, dashboard) {
+  pi.on('session_start', (_event, ctx) => { dashboard.start(ctx); });
+  pi.on('session_shutdown', () => { dashboard.stop(); });
+  pi.on('model_select', (_event, ctx) => { dashboard.select(ctx); });
+  // ponytail: O(session entries) aggregation; throttle streaming to 4Hz. Use
+  // incremental accounting only if very large sessions make this measurable.
+  let lastStreamUpdate = 0;
+  pi.on('message_update', (_event, ctx) => {
+    const now = Date.now();
+    if (now - lastStreamUpdate >= 250) { lastStreamUpdate = now; dashboard.local(ctx); }
+  });
+  for (const event of ['thinking_level_select', 'message_end', 'turn_end', 'agent_settled', 'session_compact', 'session_tree']) {
+    pi.on(event, (_event, ctx) => { dashboard.local(ctx); });
+  }
+  pi.registerCommand('dashboard', {
+    description: 'Read-only unified snapshot; /dashboard refresh bypasses TTL (not backoff)',
+    handler: async (args, ctx) => {
+      if (!ctx.hasUI) return;
+      if (args.trim() && args.trim() !== 'refresh') {
+        ctx.ui.notify('Usage: /dashboard [refresh]', 'info');
+        return;
+      }
+      // No sendMessage/appendEntry: snapshots never enter model context or disk.
+      dashboard.local(ctx);
+      const s = await dashboard.refresh(args.trim() === 'refresh');
+      if (s && dashboard.ctx) dashboard.ctx.ui.notify(JSON.stringify(s, null, 2), 'info');
+    },
+  });
+}