@tmustier/pi-usage-extension 0.3.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.6.0] - 2026-07-17
+
+### Added
+- **Interactive graph explorer.** New third view mode (cycle with `v`): a braille line chart of usage over time for the active period, with a legend showing per-series totals and shares.
+  - Metrics (`m`): cost, tokens, messages, reasoning tokens.
+  - Grouping (`g`): by provider, by model, by thinking level, or total only — top 6 series plus an `other` rollup, with a bold Total line always drawn.
+  - Cumulative running totals or per-bucket rates (`c`), hourly buckets for day/week periods and daily buckets for Last 30 Days / All Time.
+  - Legend filtering: `↑`/`↓` moves the cursor, `Enter`/`Space` hides or shows a series, `a` shows all. The y-axis rescales to the visible series so small series can be inspected by hiding large ones.
+- **Thinking level and reasoning tokens.** Session parsing now replays `thinking_level_change` entries (compact and spaced JSON styles) to attribute a thinking level to each assistant message, and records `usage.reasoning` token counts. Messages before the first recorded change appear as `unknown`.
+
+### Changed
+- On-disk cache format bumped to v2 (per-message thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild; older caches are ignored safely.
+
+## [0.5.0] - 2026-07-17
+
+### Added
+- **Last 30 Days period.** New tab between Last Week and All Time covering the last 30 calendar days including today (from midnight 29 days back, DST-safe). Available in both the table and insights views.
+
+## [0.4.0] - 2026-07-17
+
+### Performance
+- `/usage` no longer re-reads and JSON-parses every session JSONL file on every open. On a real 5.2 GB / 3,310-file corpus, warm opens went from ~17 s to ~0.3 s (~50×) and the one-off cold build from ~17 s to ~7 s, with peak memory roughly halved.
+- **On-disk cache.** Per-file extraction results are persisted to `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Only new or changed session files are re-parsed; entries for deleted files are evicted. Deleting the cache file forces a full rebuild — it is recreated automatically.
+- **Buffer-level pre-filter.** Session files are scanned as raw bytes and only lines that can be a session header or an assistant message are UTF-8-decoded and JSON-parsed; the multi-megabyte tool-result lines that dominate session files are skipped with a cheap byte search. Both compact (`"role":"assistant"`) and spaced (`"role": "assistant"`, seen in imported third-party session files) JSON styles are matched.
+- Changed files are parsed with bounded concurrency, and a cancelled cold build persists partial progress so the next open resumes instead of restarting.
+
+### Changed
+- Data collection, caching, and insights moved from `index.ts` into `usage-extension/data.ts`, with tests in `tests/usage-data.test.mjs`. Verified equivalent to the previous parser across all 3,310 real session files (zero extraction mismatches).
+- Files without a session header (which are ignored, as before) no longer register their messages in the branch-dedupe hash set, so an identical message in a later, valid session file is now counted instead of silently dropped.
+
 ## [0.3.2] - 2026-05-07
 
 ### Changed

package/README.md

@@ -7,7 +7,7 @@ A Pi extension that displays aggregated usage statistics across all sessions.
 ## Compatibility
 
 - **Pi version:** 0.42.4+
-- **Last updated:** 2026-04-19 (0.3.1)
+- **Last updated:** 2026-07-17 (0.6.0)
 
 ## Installation
 
@@ -57,15 +57,28 @@ In Pi, run:
 
 ### Views
 
-`/usage` has two view modes, toggled with `v`:
+`/usage` has three view modes, cycled with `v`:
 
 - **Table** (default) — per-provider / per-model stats with cost and token breakdown (screenshot at the top of this page).
 - **Insights** — narrative characteristics of your cost for the active time period, e.g. *"X% of your cost was at >150k context"*. Insights are **independent characteristics**, not a breakdown, so they overlap and can sum to more than 100%.
+- **Graphs** — an interactive braille line-chart explorer for usage over time (details below).
 
 ![Insights view of /usage](insights-screenshot.png)
 
 **Unit:** insights are always weighted by recorded API cost (USD). Periods with no recorded cost show an explicit empty state rather than silently switching to a different unit.
 
+### Graph explorer
+
+The **Graphs** view plots usage over time for the active period as a braille line chart, with a legend showing per-series totals and shares.
+
+- **Metric** (`m` to cycle): cost, tokens (input + output + cache write), messages, reasoning tokens.
+- **Grouping** (`g` to cycle): by provider, by model, by thinking level, or total only. The top 6 series are shown individually; the rest merge into an `other` series. A bold **Total** line is always drawn.
+- **Cumulative vs per-bucket** (`c` to toggle): running total across the period (default), or the raw per-bucket rate.
+- **Filtering**: move the legend cursor with `↑`/`↓` and toggle series visibility with `Enter`/`Space` (`a` shows all again). The y-axis rescales to the visible series — hide the big lines to zoom into the small ones.
+- **Buckets**: hourly for Today / This Week / Last Week, daily for Last 30 Days / All Time.
+
+Thinking levels are replayed from `thinking_level_change` entries in each session file; messages before the first recorded change appear as `unknown`. Reasoning token counts come from `usage.reasoning` where providers report them.
+
 The insights currently shown:
 
 | Insight | Threshold |
@@ -83,6 +96,7 @@ The insights currently shown:
 | **Today** | From midnight (00:00) today |
 | **This Week** | From Monday 00:00 of the current week |
 | **Last Week** | Previous week (Monday 00:00 → this Monday 00:00) |
+| **Last 30 Days** | Rolling window: the last 30 calendar days including today (from midnight 29 days back) |
 | **All Time** | All recorded sessions |
 
 Use `Tab` or `←`/`→` to switch between periods.
@@ -113,11 +127,24 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 | Key | Action |
 |-----|--------|
 | `Tab` / `←` `→` | Switch time period |
-| `↑` `↓` | Select provider *(table view)* |
-| `Enter` / `Space` | Expand/collapse provider to show models *(table view)* |
-| `v` | Toggle between Table and Insights view |
+| `↑` `↓` | Select provider *(table)* / move legend cursor *(graphs)* |
+| `Enter` / `Space` | Expand/collapse provider *(table)* / toggle series visibility *(graphs)* |
+| `v` | Cycle Table → Insights → Graphs view |
+| `m` | Cycle metric: cost / tokens / messages / reasoning *(graphs)* |
+| `g` | Cycle grouping: provider / model / thinking level / total *(graphs)* |
+| `c` | Toggle cumulative vs per-bucket *(graphs)* |
+| `a` | Show all series *(graphs)* |
 | `q` / `Esc` | Close |
 
+## Performance & Caching
+
+`/usage` builds its stats from every session JSONL file under `<agentDir>/sessions`. To keep opens fast on large histories (multi-GB, thousands of files):
+
+- **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
+- **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
+- The cache is safe to delete at any time; it is rebuilt automatically. Corrupt or version-mismatched caches are ignored and rebuilt rather than trusted.
+- **0.6.0 bumps the cache format to v2** (adds thinking level and reasoning tokens per message). The first open after upgrading does a one-off full rebuild, then warm opens are fast again.
+
 ## Provider Notes
 
 ### Cost Tracking