docs: document UBB support and pooled exhaustion state

euxx · euxx · commit b33e3f93f5a2 · 2026-05-27T18:16:06.000+08:00
- README: mention auto-adapt to billing mode in the tagline; tooltip
  bullet describes title switch; status-bar table adds the `100%` red
  pooled-exhaustion row.
- CHANGELOG: 0.5.0 entry covering UBB title switch, new plans, reset
  priority, precise `used` via quota_remaining, pooled exhaustion, and
  the entitlement parse change.
- DEVELOPMENT: add an "Upstream Reference (vscode)" section pointing
  at parseQuotas, the dashboard, defaultAccount, and their tests, so
  future field-shape audits know where to diff.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [0.5.0] - 2026-05-27
+
+### Added
+
+- **Token-based billing (UBB) support**: auto-detects GitHub's new credit-based billing mode via the `token_based_billing` field. The tooltip title switches between **Copilot Premium Requests** (legacy) and **Copilot Credits** (UBB), so the count line stays a familiar `Used: 90 / 300 (30%)`. Overage line still labels its unit (`Overage: 5 requests` vs `Additional credits: 5`).
+- **`individual_max` (Max) and `individual_edu` (Student) plans** in the plan-name map.
+- **Per-snapshot `quota_reset_at`** (Unix seconds) read with top priority under UBB; falls back to `quota_reset_date_utc` then `quota_reset_date`. Shared by all return paths so pooled-exhausted users still see real reset times.
+- **Precise `used` calculation** via `quota_remaining` when present (avoids float precision loss from percentage-based reverse calculation).
+- **Pooled entitlement exhaustion**: enterprise unlimited plans signaling `has_quota=false` (without overage) now display `100%` red instead of misleadingly showing `∞`. Tooltip surfaces "Quota: Unlimited · pool exhausted" with the reset date.
+
+### Changed
+
+- `entitlement` parse handles string values (`'300'`) emitted under UBB; `entitlement: '0'` (not unlimited) now correctly routes to the no-data state, matching upstream `parseQuotas` behavior. Missing `entitlement` (`undefined`) is preserved as a distinct case and stays on the normal path.
+
 ## [0.4.4] - 2026-04-30
 
 ### Changed
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -66,3 +66,18 @@ Tests mock `fetch` globally — no network calls are made.
 - **Auth**: VS Code `authentication.getSession('github', ...)` — uses the user's existing GitHub session; cancellation handled gracefully via inner try/catch
 - **Auto-refresh**: Configurable interval (1–60 min, default 5 min) via `githubCopilotUsage.refreshIntervalMinutes`
 - **Status bar position**: Priority `100.099999` — places the indicator just to the right of the Copilot icon (`chat.statusBarEntry` at `100.1`)
+
+### Upstream Reference (vscode)
+
+This extension parses the same `copilot_internal/user` payload the VS Code Copilot UI consumes. When the API or field semantics change, these are the upstream files worth diffing — clone [microsoft/vscode](https://github.com/microsoft/vscode) alongside this repo and check them periodically.
+
+| Path                                                                       | What to watch for                                                                                                                                                                |
+| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/vs/workbench/services/chat/common/chatEntitlementService.ts`          | `parseQuotas` — source of truth for field priority, types, and edge cases (entitlement string→number, `quota_reset_at`, Free CFI shape, etc.).                                   |
+| `src/vs/workbench/contrib/chat/test/common/chatEntitlementService.test.ts` | Upstream test cases for `parseQuotas` — the canonical fixture set; new payload shapes usually land here first.                                                                   |
+| `src/vs/workbench/contrib/chat/browser/chatStatus/chatStatusDashboard.ts`  | How the dashboard renders unlimited / pooled-exhausted / overage / UBB states — useful when deciding what our single-value status bar shows.                                     |
+| `src/vs/workbench/contrib/chat/test/browser/chatStatusDashboard.test.ts`   | Dashboard render expectations — mirrors what end users see in VS Code.                                                                                                           |
+| `src/vs/platform/defaultAccount/common/defaultAccount.ts`                  | `IDefaultAccount` field types — confirms shape of `chat_*`, `quota_*`, and `token_based_billing` flags.                                                                          |
+| `src/vs/base/common/defaultAccount.ts`                                     | Plan ID enum (`free` / `individual` / `individual_pro` / `individual_max` / `individual_edu` / `business` / `enterprise`) — keep `PLAN_MAP` in [src/api.js](src/api.js) in sync. |
+
+Quick check: `git -C ../vscode log --since=<last-check> -- src/vs/workbench/services/chat/common/chatEntitlementService.ts src/vs/platform/defaultAccount/common/defaultAccount.ts` surfaces relevant changes without scanning the whole tree.
diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 # GitHub Copilot Usage
 
 <div>
-  <p>Shows Copilot Premium request quota usage in the VS Code status bar, right next to the Copilot icon.</p>
+  <p>Shows Copilot Premium request / Credit usage in the VS Code status bar, right next to the Copilot icon. Adapts to legacy or token-based billing.</p>
   <p>e.g., <code>25%</code> normal · <code>75%</code> yellow warning · <code>95%</code> red critical.</p>
 </div>
 
@@ -10,7 +10,7 @@
 ## Features
 
 - **Status bar**: shows used percentage (`15%`), turns yellow/red near threshold
-- **Hover tooltip**: plan, used / quota, overage (if any), reset date, last-updated timestamp — with a refresh button and a link to [Premium request analytics](https://github.com/settings/billing/premium_requests_usage)
+- **Hover tooltip**: titled **Copilot Premium Requests** or **Copilot Credits** depending on the billing mode; shows plan, `Used: X / Y (Z%)`, overage, reset date, last-updated timestamp — with refresh button and link to [Premium request analytics](https://github.com/settings/billing/premium_requests_usage)
 - **Auto-refresh**: configurable interval (default 5 min)
 - **Zero config**: uses your existing VS Code GitHub account sign-in
 
@@ -22,19 +22,20 @@
 
 ## Status bar states
 
-| Display        | Meaning                                            |
-| -------------- | -------------------------------------------------- |
-| `25%`          | Normal usage                                       |
-| `75%` (yellow) | Warning threshold reached                          |
-| `90%` (red)    | Critical threshold reached                         |
-| `111%` (red)   | Overage — actual usage exceeds                     |
-| `∞`            | Unlimited plan                                     |
-| `—`            | No premium quota data (plan has no tracked limit)  |
-| `⟳`            | Loading                                            |
-| `✕`            | Server error or access denied                      |
-| `⚠`            | Offline or rate limited — no cached data available |
-| `25% ⚠`        | Last known data — offline for > 1 hour             |
-| `Sign in`      | Not signed in — click to sign in                   |
+| Display        | Meaning                                                         |
+| -------------- | --------------------------------------------------------------- |
+| `25%`          | Normal usage                                                    |
+| `75%` (yellow) | Warning threshold reached                                       |
+| `90%` (red)    | Critical threshold reached                                      |
+| `100%` (red)   | Pooled entitlement exhausted (enterprise unlimited, no overage) |
+| `111%` (red)   | Overage — actual usage exceeds                                  |
+| `∞`            | Unlimited plan                                                  |
+| `—`            | No premium quota data (plan has no tracked limit)               |
+| `⟳`            | Loading                                                         |
+| `✕`            | Server error or access denied                                   |
+| `⚠`            | Offline or rate limited — no cached data available              |
+| `25% ⚠`        | Last known data — offline for > 1 hour                          |
+| `Sign in`      | Not signed in — click to sign in                                |
 
 ## You may also like
 
