dsh-token-panorama 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiuwu02
+
+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

@@ -1,3 +1,444 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Token Panorama for DSH
+
+A DeepSeek Harness bundle that shows where every session's tokens go: one panel with lifetime totals, a
+calendar heatmap, a trend chart, a per-model breakdown, a per-session usage table, and CSV/JSON export. Two
+tool groups come with it: context clear/compact buttons, and a prompt optimization button.
+
+Everything is read from the platform's own session persistence service, so nothing is scraped from logs and no
+third-party dependency is required.
+
+## Features
+
+- **Lifetime totals**: cumulative tokens, plus the input / output / cache-read / cache-write split and call count.
+- **Cache hit rate**: cache reads as a share of all input-side tokens, with absolute hit and miss counts.
+- **Cost estimate**: priced against DeepSeek's peak / off-peak bands, each band's amount shown separately.
+- **Calendar heatmap**: GitHub-style week columns or one mini calendar per month; switch with the `Week` /
+  `Month` control.
+- **Trend chart**: daily / weekly / monthly / yearly granularity, with a hover readout per point.
+- **Model breakdown**: tokens and calls per model, sorted by volume.
+- **Workspace breakdown**: grouped by the working directory each session header records, so you can see which
+  project costs the most.
+- **Session usage tree**: main sessions only by default; opening one reveals the subagent sessions it owns, so
+  the card does not grow with the subagent count. Sortable by column, archived sessions marked and hideable,
+  and row figures follow the selected date range.
+- **Paging**: 40 session groups per page, so a large history never renders every row at once.
+- **Shared time range**: the filter bar is the one control every card reads (All / Today / Last 24 hours /
+  This week / Last 7 days / This month / Last 30 days, plus a pair of date inputs). The heatmap, trend, cost,
+  peak, model, session and workspace cards all recompute from the same span.
+- **Hourly axis**: narrowing to Today or Last 24 hours switches the trend card to hours, filling in the quiet
+  hours so the line cannot cut across an idle stretch.
+- **Export**: daily buckets as CSV (UTF-8 BOM + CRLF) or JSON, plus a separate per-session CSV with the
+  workspace, parent session, and cost columns.
+- **Incremental refresh**: a per-session revision token decides what to re-read, so a refresh only decodes
+  sessions that actually changed.
+- **Holiday auto-update**: any year is fetched at runtime and cached, so a new year needs no new build.
+- **Context actions**: Clear (orange) and Compact (green) buttons in the dock under the composer, plus the
+  `/clear-context`, `/compact-context` and `/compact` commands. Compact runs mid-conversation: it fixes a cut
+  before summarizing, so everything written while the summarizer works stays verbatim behind the summary, and
+  the checkpoint reuses the platform's own "context compacted" marker with the item and token counts. A
+  `/compact` run folds the command row and the marker into one merged card, like the platform's own compaction.
+  Clear replaces the whole surface and therefore needs an idle session.
+- **Prompt optimization**: an Optimize button in the input box toolbar sends the draft to a configurable
+  optimizer model and pastes the rewrite back into the composer; attachments are untouched. The request can
+  also carry an excerpt of the session's context, so a prompt that says "this function" rewrites into one that
+  names it. Instruction, route and the context toggle live on the **Prompt optimization** settings tab.
+- **Bilingual**: Chinese and English follow the platform locale.
+
+## Requirements
+
+- DSH `>= 0.2.1-rc.3` (declared as `dsh.engines.dsh`).
+- A profile whose client runs the Web UI; the bundle registers into `sidebar.panellist` and `main`.
+
+## Install
+
+Install from a local directory through the Plugins page or the plugin manager, pointing at the package
+directory (the folder containing `package.json`):
+
+```
+plugin_manager install_bundle target="<absolute path to this directory>"
+```
+
+After installation the sidebar shows a **Token Panorama** entry; selecting it opens the main panel.
+
+To remove it, uninstall the `dsh-token-panorama` bundle from the Plugins page.
+
+## npm package
+
+The plugin is also published to the public npm registry as `dsh-token-panorama`. Storefronts
+(the awesome-dsh-plugin catalog and the in-app market) can then install it by package name
+and show a download figure, instead of falling back to the GitHub Release tarball.
+
+- Publish a new version with `npm publish --access public`. npm requires either two-factor
+  authentication or a granular access token with Bypass 2FA enabled.
+- The catalog reads the `name` field of the repository `package.json`, confirms that package on
+  the registry, and requires the npm package `repository` field to point back at this GitHub
+  repo. The mapping is discovered automatically; no field needs to be added to any listing.
+- The download figure is the npm download count over a rolling 30-day UTC window
+  (`api.npmjs.org/downloads/point`), refreshed by the catalog nightly probe. It is not a
+  page-view or visit count: neither the catalog nor the market exposes any view metric.
+  GitHub Release asset downloads are a separate number and do not feed this field.
+- Every change bumps `version` in `package.json`; publish that version too, so the registry
+  `latest` tag and the catalog `version` stay in step.
+
+## Usage
+
+1. Select **Token Panorama** in the sidebar.
+2. Choose a range from the filter bar, or type a `From` / `To` pair.
+3. Switch the heatmap between `Week` and `Month`, and the trend between `Hour` / `Day` / `Week` /
+   `Month` / `Year` (`Hour` appears only on a sub-day range).
+4. Hover any trend point for its exact numbers.
+5. The **Session usage** tree lists main sessions by default. Select the `▶` at the start of a row to open it,
+   revealing every subagent session it owns. Select a column header (Session / Tokens / Calls / Created) to
+   sort, clear `Show archived` to see only sessions still in use (the choice is remembered across visits), and
+   use `Export sessions CSV` to save what the table currently shows.
+6. Page through large histories with `Previous` / `Next`; each page holds 40 session groups.
+7. Use **Refresh** to re-scan, or **Export** to save the daily buckets as CSV / JSON.
+8. Use **General settings** to open the settings window and change the zone, currency, peak windows, holidays,
+   and price sheet; saving re-prices immediately.
+
+The panel refreshes automatically when it opens; large histories load in about a second because only changed
+sessions are decoded after the first pass.
+
+## Billing configuration
+
+Every billing parameter is a plugin config entry. Open the settings window from the `General settings` button
+in the panel header to edit them online; saving re-prices immediately, with no DSH restart.
+
+The window edits the config by structure, not by field name: model prices are a table, peak schedules are
+reusable profiles, and holidays are a checklist, none of which a generic key/value editor can express. It has
+six tabs:
+
+| Tab | Contents |
+| --- | --- |
+| **Models & prices** | One row per model with four independent price inputs (miss input, cache-hit input, cache write, output), plus the peak toggle with its schedule picker and the delete button pinned to the right edge |
+| **Peak schedules** | Reusable profiles: name, automatic mode, any number of start–end windows, off-peak ratio |
+| **Holidays** | Calendars shipped with the plugin; tick to enable |
+| **Context** | The compaction instruction, its model route, the live context readout, and the automatic and segmented compaction switches |
+| **Prompt optimization** | The optimizer instruction, its model route, and whether the request carries an excerpt of the session's context |
+| **General** | Billing time zone and currency |
+
+The window can **export** the billing configuration to JSON and **import** a shared one; an import only
+fills the form, so nothing changes until Save is pressed.
+
+The model list defaults to the models the logs actually contain, ordered by usage, so opening the window
+puts a row in front of you for every model currently being charged. A model with no price row yet shows
+"not priced" and an *add price* button.
+
+Every model is priced on its own. A model missing from the sheet falls back to `defaultPrice`, and the cost
+card names it ("kimi-k3.1-pro is not priced; charging the default") instead of quietly billing zero.
+
+Four rates, billed separately. A provider does not treat every input token alike, so the sheet has one
+column per thing it charges for:
+
+| Column | What it bills | When the provider does not charge for it |
+| --- | --- | --- |
+| Miss input | Input sent for the first time, with no prefix-cache hit | The listed rate |
+| Cache-hit input | Input served from the prefix cache | 0 |
+| Cache write | Input stored into the cache | 0 |
+| Output | What the model generated | The listed rate |
+
+Keeping the two cache columns apart matters: a write stores input and a read fetches it back, and their rates
+commonly differ by more than ten times. Collapse them into one number and a session warming a cache prices
+too cheaply while a session reusing one prices too expensively. A cache write is also excluded from the
+hit-rate denominator: it is a write, not a read.
+
+Peak pricing is a separate, reusable item. One schedule can back several models: switch the model's toggle on
+and pick the schedule name. A model with the toggle off bills one rate all day, the full listed price, so it
+counts in the peak column rather than the discounted one. Renaming a schedule renames every model's reference
+with it; deleting one leaves those references behind, and a model pointing at a missing schedule bills flat
+until it is re-pointed (the row says so and offers the picker).
+
+Off-peak is a ratio, not a second price. The schedule's off-peak ratio is a share of the listed price (0.5 by
+default), so there is one price sheet to maintain and changing the ratio re-prices both bands at once.
+
+### Automatic modes
+
+The mode decides which days a schedule applies to, following the shape of an alarm's repeat rule:
+
+| Mode | Meaning |
+| --- | --- |
+| Every day | No weekday or holiday filter |
+| Statutory workdays (skips holidays) | Monday to Friday, excluding any enabled holiday |
+| Statutory holidays (skips workdays) | Only on enabled holidays |
+| Monday to Friday | Weekday only; ignore holidays |
+| Custom | Any combination of the seven weekdays |
+
+### Time windows
+
+A schedule holds any number of start–end windows, each entered on a 24-hour clock. **More than one window is
+necessary**: DeepSeek's peak band is split around the lunch break (09:00-12:00 and 14:00-18:00), and collapsing
+it into one 09:00-18:00 span bills the break at the peak rate: peak tokens would read ~450M instead of ~404M.
+
+An `end` earlier than its `start` wraps midnight, so `22:00`-`02:00` is one entry.
+
+### Holidays
+
+Holiday dates are fetched over the network at runtime and cached under the profile, so a new year works without
+shipping a new plugin build. Only years that have no data yet are fetched: a published year never changes again,
+while a year the sources have not published (for example the next one) is retried once a day. Three keyless
+sources are tried in order, and a year that every source rejects keeps whatever was already cached.
+
+The plugin still starts with the 2026 dates built in, so pricing is correct on the very first run, before any
+request leaves the process. Settings shows how many years are loaded and has a refresh button that forces a
+re-fetch. The statutory-holiday calendar is on by default.
+
+The bundled list is seed data, not the source of truth: once a year is fetched its network copy wins.
+
+### Context actions
+
+Two buttons sit in the dock under the composer, in the same row as the context-usage meter they act on:
+**Clear context** (orange) on the left and **Compact context** (green) on the right. Both are also slash
+commands (`/clear-context` and `/compact-context`), so they work without the mouse.
+
+They differ in what they replace. Clear takes the whole surface and therefore needs an idle session: a step
+appending during the rewrite would be dropped with the history it belongs to. Compact takes only the span it
+selected *before* summarizing, up to the last cut that does not split a tool-call/result pair, so it works
+mid-conversation, and everything written while the summarizer runs is replayed verbatim behind the checkpoint.
+The session and its log are untouched either way: the events stay on disk, the surface only stops showing the
+replaced part, and the context window is freed.
+
+- **Clear**: writes a one-line placeholder. It is not a summary; nothing before the next message is retained.
+- **Compact**: calls the model directly to write a summary, then replaces the cut with it. It runs on the
+  session's provider and model unless the Context tab overrides them. The span is replayed as the messages it
+  really holds (same system prompt, same tool definitions, instruction appended last), so the provider's
+  prefix cache covers the history and the call bills as a cache read instead of a second full send. No
+  subagent is started, so the summarizer has no session, no tools of its own, and nothing it could edit.
+
+After either one, the transcript shows one command card, with no duplicate note under the buttons. The two
+report different things: Clear gives the item and token counts before and after the swap, Compact adds the
+character count of the summary it wrote. They ride the platform's own `command/run` / `command/done` events,
+so the card is visible and expandable but never enters the surface: the model's context stays free of its own
+bookkeeping.
+
+The prompt the compaction model reads is editable on the **Context** settings tab, which also picks the
+model's provider and model; leaving those empty inherits the session's. The default prompt asks for the goal,
+decisions and their reasons, verbatim paths and signatures, error text, and open work, and forbids mentioning
+the compaction itself.
+
+The same tab carries three more things about how much window is left:
+
+- **Context usage** is the live total for the current session, built from the real system prompt, tool
+  definitions, and conversation messages, next to the selected model's input window, the share in use, and
+  the three-part split.
+- The **automatic compaction** switch and its **trigger threshold** (75% by default) decide when this plugin
+  compacts on its own, before the window is full. The trigger rides the same `agent/pre-step` event the platform
+  engine uses, but this plugin runs it and writes no platform config. A profile may disable that engine outright
+  (billion-context disables `dsh-compaction-basic` as a whole, and a preset's nested row is not reachable
+  through the config editor anyway), and then a saved switch would enforce nothing. The decision is made on the
+  three-part real total described above, not the usage-anchored figure the platform panel prints at the top: on
+  a long session that one reads 112K while the same request really carries 2.3M. Two compactions of one
+  session are at least a minute apart, so a history still over the threshold right after being summarized does
+  not pay for another summary on the very next step.
+- **Segment when over the window** decides what happens once the history is larger than the summarizer's
+  window. Off: the oldest part is dropped, only the newest records that fit are summarized, and the excerpt
+  says how many were omitted. On: the span is cut into segments, each summarized in parallel, and a final
+  request merges them into the one summary that replaces the span. Nothing is dropped, and no single request
+  exceeds the window; a long conversation that used to hang or come back empty was running into exactly that
+  request.
+- Compaction measures first. A history past two thirds of the summarizer's window falls back to a head-and-tail
+  excerpt when segmenting is off: the head keeps the goal and the constraints, the tail keeps whatever is in
+  progress, and the omitted middle is marked explicitly. A span that reaches into the running turn is no
+  different: the summarizer is handed the messages themselves, so the summary covers exactly what the
+  checkpoint will replace.
+- The compaction lock is opened before the summarizer is called, not after. A second request then answers
+  "already in flight" instead of paying for the same summary twice, and the platform's own engine backs off
+  rather than racing this one.
+
+Clearing an already-cleared session is a no-op that reports success: rewriting one placeholder with another
+identical one is not an error.
+
+### Validation
+
+The platform schema and the plugin each validate before a save lands: an unknown zone, a malformed `HH:MM`, a
+negative price, an off-peak ratio outside (0, 1], or an unknown automatic mode is rejected with the offending
+field named.
+
+### Upgrading
+
+A 1.0 configuration (one flat `peakWindows` list, six-field prices named `hitPeak` / `missPeak` / `outPeak`,
+holidays as a date array) is migrated on read: the peak half becomes the listed price, a model that had an
+off-peak rate is attached to the `standard` schedule, and the date array folds back into calendar keys. The
+migration is read-only, so the file on disk keeps its old shape until you save from the window.
+
+Every string in the window lives in the `ZH` / `EN` dictionaries in `client.js`, 230 keys with identical key
+sets across both languages.
+
+Saving goes through the platform's `configEditor` service, which validates the schema, writes the whole config
+into the profile's `cordis.patch.yml`, and triggers a hot reload. The plugin validates once more first, so a bad
+value comes back as a message naming the offending field instead of a Loader-level failure. When the profile has
+no such service or no matching row, the window degrades to read-only and says why.
+
+- **Holidays win over weekdays**: a listed day bills off-peak all day whatever weekday it falls on.
+- **Validation runs at load**: an unknown zone, a malformed `HH:MM`, an impossible date, or a negative price
+  is rejected with a message naming the offending field.
+
+> DeepSeek's peak rule reads "Monday through Friday", so make-up working days (weekends worked for a holiday
+> swap) still bill off-peak; the panel does not treat them as peak. Prices are per million tokens, matching the
+> provider's published sheet.
+
+## How the data is collected
+
+- **Source**: the Host `sessionPersistence` service lists every session with an opaque `revision`. Sessions
+  whose revision is unchanged are skipped. For the rest, the log's Zstandard frames are walked without
+  inflating them, so only the frames appended since the last pass are decoded — a pass over an
+  unchanged corpus decodes nothing at all, and one that has to re-read a session decodes its tail
+  rather than its whole history.
+- **Counting**: each `assistant/message` event carrying `data.usage` contributes one call. The total prefers
+  `usage.totalTokens`, falling back to `inputTokens + outputTokens + cacheReadTokens + cacheWriteTokens`.
+- **Scope**: every session in the profile, including subagent sessions (`header.origin === 'subagent'`) and
+  archived sessions; the footer counts main, subagent, and archived separately.
+- **Session titles**: taken from the last `session/title` event in each session's own log, never from mutable
+  metadata.
+- **Archived flag**: read from `workspaceRegistry.archivedSessionIds`; when that service is absent the plugin
+  treats the profile as having no archived sessions and every other figure stays correct.
+- **Workspace**: taken from `cwd` in each session's header event (`type: "session"`); a session without one is
+  grouped under "(no workspace)".
+- **Lineage**: taken from `parentSession` in the same header event. A subagent whose parent is outside this
+  report is shown as a top-level entry rather than dropped.
+- **Buckets**: usage is keyed by the local calendar day of the event timestamp; billing additionally splits by
+  hour, converted through the configured zone.
+- **Cache**: the folded result is written to `~/.dsh/storages/dsh-token-panorama/usage-cache.json`
+  (`CACHE_VERSION = 5`), written atomically via a temp file and rename. Each record also carries the
+  byte offset and the highest sequence number it has folded, which is what lets the next pass resume.
+- **Projection seed**: when the Host's `sessionProjections` service is present, the plugin registers its
+  own fold (`tokenPanoramaUsage`) so the Host keeps it current as events are committed. A session whose
+  projection row is already at the log's end is adopted without reading the log at all. The row is used
+  only after its state version, zone, watermark and log identity all agree; anything else falls back to
+  reading the log, so the seed can save work but never change an answer. Without the service the plugin
+  works as before. An unreadable log is remembered by revision for ten minutes instead of being decoded
+  again on every pass.
+- **Accuracy**: totals are exactly the sum of the underlying `usage` records; the panel never estimates. Session
+  rows follow the selected range, their sum over any day equals that day's heatmap figure exactly, and the
+  hourly cost is rolled into the day, model, and session dimensions, whose sums all equal the grand total.
+
+## HTTP API
+
+The Host registers a prefix route at `/token-stats/api`. Every request must pass the platform's own
+Host/Origin fence (`ctx.connection.requestRejection`) and be `POST` with a JSON body.
+
+| Method       | Body                | Purpose                                                         |
+| ------------ | ------------------- | --------------------------------------------------------------- |
+| `summary`    | `{}`                | Return the current snapshot, re-scanning only changed sessions. |
+| `summary`    | `{"refresh": true}` | Distrust this plugin's folds and rebuild them, still seeding from any Host projection row that proves itself. |
+| `refresh`    | `{}`                | Alias for a forced refresh.                                     |
+| `config`     | `{}`                | Return the live config, its field list, and editability. `models` carries the Host's live model catalog (each entry with its context window). |
+| `saveConfig` | `{"value": {...}}`  | Validate and persist a config; returns it with the field list. Automatic compaction runs in this plugin and writes no platform config, so there is no "did the mirror land" field. |
+| `holidays`   | `{}`                | Force a re-fetch; returns whether it changed and the per-year list. |
+| `clearContext` | `{"sessionId": "..."}` | Replace that session's whole surface with a placeholder. |
+| `compactContext` | `{"sessionId": "..."}` | Summarize that session with a direct model call and replace the surface. |
+| `contextPressure` | `{"sessionId": "..."}` | Measure one session: total tokens, the system/tools/messages split, the routed model's context window, and the share in use. |
+
+Response shape:
+
+```json
+{
+  "ok": true,
+  "value": {
+    "generatedAt": 1793511000000,
+    "lastScanAt": 1793510999000,
+    "scan": null,
+    "sessions": { "total": 0, "subagent": 0, "main": 0, "archived": 0 },
+    "totals": {
+      "input": 0,
+      "output": 0,
+      "cacheRead": 0,
+      "cacheWrite": 0,
+      "total": 0,
+      "calls": 0
+    },
+    "days": [["2026-11-01", 0, 0, 0, 0, 0, 0, 0]],
+    "models": [["deepseek-v4.1-flash", 0, 0, 0]],
+    "cache": { "hits": 0, "misses": 0, "hitRate": 0 },
+    "billing": {
+      "currency": "CNY",
+      "timeZone": "Asia/Shanghai",
+      "cost": 0,
+      "peakCost": 0,
+      "offPeakCost": 0,
+      "peakTokens": 0,
+      "offPeakTokens": 0,
+      "peakCalls": 0,
+      "offPeakCalls": 0,
+      "hitRate": 0,
+      "hits": 0,
+      "misses": 0,
+      "priced": ["deepseek-v4.1-flash"],
+      "unpriced": []
+    },
+    "sessionRows": [],
+    "firstDay": "2026-10-30",
+    "lastDay": "2026-11-01"
+  }
+}
+```
+
+`days`, `hours` and `models` rows are `[key, input, output, cacheRead, cacheWrite, total, calls, cost,
+peakInput, peakOutput, peakCacheRead, peakCacheWrite, peakTotal, peakCalls, peakCost]`. `sessionRows`
+rows are `[sessionId, title, createdAt, isSubagent(0|1), isArchived(0|1), total, calls, parentId,
+dayRows, cost, workspace, slotRows, models]`, where `dayRows` is `[day, …]` and `slotRows` is
+`[hour, model, input, output, cacheRead, cacheWrite, total, calls, cost, isPeak(0|1)]`. Archive state
+comes from `workspaceRegistry.archivedSessionIds`; archived sessions keep their logs on disk, so they
+also appear in `sessionPersistence.list()`.
+
+Slots are the finest fact the Host has, so the Client can narrow a session to a range and a model from the
+row alone. The peak flag travels with them because only the Host knows the schedule and the holiday calendar,
+and a second copy of those rules in the Client would eventually disagree with it.
+
+Three extra per-model fields let the Client narrow the whole page to one model without a second request:
+
+- `modelDays`: `[model, dayRows]`, used to rebuild that model's trend and heatmap over any range.
+- `modelHours`: `[model, hourRows]`, the hour-grain twin of `modelDays`.
+- `modelBilling`: `[model, {cost, peakCost, offPeakCost, peakTokens, offPeakTokens, peakCalls,
+  offPeakCalls, hits, misses}]`, used to rebuild its cost, peak/off-peak and hit-rate figures.
+
+Each family sums back to the global `totals` and `billing` exactly.
+
+## Package layout
+
+```
+package.json        manifest: exports, dsh.bundle.patch, dsh.client, engines
+cordis.patch.yml    inserts this bundle into the profile patch
+index.js            Host entry: Config validation, HTTP route, plugin lifecycle
+lib/time.js         Zone math, hour bucketing, numeric normalisation
+lib/scan.js         Folding session events into hour × model slots
+lib/schema.js       Config schema, default price sheet, field descriptions
+lib/billing.js      Peak rules, pricing, legacy-config migrations
+lib/holidays.js     Network fetch, per-year cache, built-in seed
+lib/contextops.js   Surface replacement for clear / compact, the real three-part measurement, and segmentation
+lib/store.js        Revision-keyed cache, the frame-level scan, and the snapshot (per day / per model)
+lib/frames.js       Walking a stored log's Zstandard frames to decode only what is new
+lib/projection.js   The tokenPanoramaUsage projection unit the Host keeps current
+lib/http.js         Request body reading and JSON responses
+client.js           Client half: panel, heatmap, trend chart, session tree, workspaces, export
+locale/en.json      plugin metadata (English)
+locale/zh.json      plugin metadata (Chinese)
+icon.svg            plugin icon (reachable via the "./icon" export)
+icon-prompt-optimize.svg  Optimize button icon (the same graphic is inlined in client.js)
+```
+
+UI strings live in `client.js` (`ZH` / `EN`) and register through `ctx.locale.register`; the `locale/*.json`
+files only carry the plugin title and description shown by the Plugins page.
+
+`schemastery` is resolved at runtime from the profile directory (see `schemaLibrary()`) and is deliberately
+**absent from `package.json` `dependencies`**: this bundle installs as a `link:`, so its own dependencies are
+never installed, and declaring one would only make the module fail to load.
+
+## Notes and limits
+
+- The heatmap, trend, and billing use the configured `timeZone` (default `Asia/Shanghai`, matching how DeepSeek
+  bills), not the machine's local zone.
+- A very long history renders one heatmap column per week; the strip scrolls horizontally rather than shrinking
+  below legibility.
+- Usage is attributed to models exactly as recorded; sessions predating usage reporting contribute nothing.
+- A model absent from the price sheet bills at `defaultPrice`, and the cost card names it rather than pricing it
+  silently.
+- Make-up working days bill off-peak per the rule's literal wording; switch a schedule to Custom and tick those
+  weekdays to count them as peak.
+- The bundle reads session persistence and the archive list, registers one HTTP prefix route, and exposes one
+  Config schema.
+- The context actions rewrite the session surface (the `compaction/*` pair plus one surface replacement), so they
+  need four platform services: `commands`, `tokenMeter`, `agents`, and `llm`. On a profile missing any of them
+  those two buttons and commands are unavailable there; the statistics are unaffected. Replaced events are never
+  deleted from the log.
+- A compaction cannot rewrite until the model has finished writing, so one run takes as long as the session
+  length and chosen model require. The session stays usable throughout: the rewrite waits for it to go idle.