dsh-consumption-badge 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zlc13
+
+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,177 @@
-# Temporary Holding Version
+# dsh-consumption-badge
 
-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.
+A **persistent** DSH (DeepSeek Harness) Web UI plugin that puts a live consumption badge
+next to every assistant message, and opens a detail panel with the session's spend curve.
+
+```
+⛽ 25.6k | ≈¥0.020 | valley
+```
+
+- **Collapsed pill** – session-cumulative tokens, estimated cost (always prefixed `≈`), and the
+  current peak/valley tier (red `peak`, green `valley`), injected into
+  `conversation.chat.assistant-actions` right after the shipped copy/branch controls.
+- **Detail modal** (centered, blurred backdrop, `Esc` or backdrop-click to close):
+  cumulative tokens with hit/miss/output split, estimated cost, current pricing tier,
+  DeepSeek account balance, and a **per-turn dual-axis line chart**
+  (left axis: tokens, right axis: ¥) with a hover tooltip showing the model,
+  input-hit / input-miss / output tokens, and the turn's peak/valley flag.
+
+Everything is an **estimate** for reference only — this plugin is not a billing system of record.
+
+## Requirements
+
+| Capability | Why |
+| --- | --- |
+| DSH `0.1.0-rc.7` or compatible | slot API `conversation.chat.assistant-actions`, `shell.overlay` |
+| `DEEPSEEK_API_KEY` in the DSH credential store | account balance (`GET /user/balance`) |
+| `curl` on `PATH` | the balance request; on Windows 10+ it ships as `C:\Windows\System32\curl.exe` |
+
+The API key is resolved **per request** through the Cordis `credentials` service and passed to
+`curl` on **stdin** (`curl -K -`), never through argv, and never reaches the browser.
+
+If the key or `curl` is missing, only the balance card degrades (it shows the reason);
+tokens, cost and the chart keep working.
+
+## Install
+
+```bash
+dsh plugin --profile web add dsh-consumption-badge
+```
+
+Then **restart the DSH process** — a host-side plugin (and the browser plugin roster) is composed
+at process start, so a page refresh is not enough.
+
+Verify:
+
+```bash
+cd "$DSH_HOME/profiles/web"
+dsh --profile web --dump-config | grep consumption-badge     # expect exactly one row
+# after restart:
+curl -s http://127.0.0.1:<port>/api/consumption/account      # expect {"ok":true,...,"model":"..."}
+curl -s -o /dev/null -w '%{http_code}\n' \
+     http://127.0.0.1:<port>/plugins/dsh-consumption-badge/client.js   # expect 200
+```
+
+### If the row does not mount
+
+Some deployments compose `dsh.profile.bundles` into `--dump-config` without mounting those rows
+at runtime. The reliable path is a roster row in the **profile's own patch layer** — add it to
+`$DSH_HOME/profiles/web/cordis.patch.yml` and remove `dsh-consumption-badge` from
+`dsh.profile.bundles` so the id is inserted exactly once:
+
+```yaml
+- insert:
+    - id: consumption-badge
+      name: 'dsh-consumption-badge'
+```
+
+The package also ships its own `cordis.patch.yml` (`dsh.bundle.patch`) with the same row for
+deployments where the bundle layer does mount. Keep only **one** of the two active.
+
+## What it reads
+
+| Data | Source |
+| --- | --- |
+| Per-turn tokens | `assistant/message.usage` events in the session log, folded per turn (`cacheReadTokens` → hit, `inputTokens + cacheWriteTokens` → miss, `outputTokens` → output; multi-step turns are summed) |
+| Turn timing | `turn/start` event time (peak/valley is attributed to **request start**) |
+| Model per turn | `request/context` / `request/header.config`; falls back to the agent default model, then `deepseek-flash` |
+| Session totals | the shipped `tokenUsage` projection when present, otherwise the folded turns |
+| Balance | `GET https://api.deepseek.com/user/balance` via curl, 60s cache |
+
+Turn records are also mirrored into browser `localStorage` under
+`dsh-consumption:<sessionId>:<turn>` so the chart survives reloads. Persistence writes are
+scheduled off the render path (`requestIdleCallback`), and the aggregation is O(turns).
+
+## Pricing model
+
+Off-peak prices in **CNY per 1M tokens**; peak multiplies everything by **2**.
+
+| Model | input cache hit | input cache miss | output |
+| --- | --- | --- | --- |
+| `deepseek-flash` | 0.02 | 1 | 4 |
+| `deepseek-v4-pro` | 0.15 | 4.5 | 13.5 |
+
+```
+cost = (hit/1e6)*hit_price + (miss/1e6)*miss_price + (out/1e6)*out_price   [×2 at peak]
+```
+
+**Peak** = Beijing time (UTC+8), Monday–Friday, 09:00–12:00 and 14:00–18:00, excluding statutory
+holidays. Everything else, plus weekends, is **valley**.
+
+Unrecognised model ids are priced as `deepseek-flash` (or `deepseek-v4-pro` when the id contains
+`pro`) and the UI marks the figure as an estimate. The table lives in `PRICES` at the top of
+`lib/client.js` — fork and edit to follow a price change.
+
+The fixed-date holiday list (`CN_FIXED_HOLIDAYS`, `MM-DD`) covers New Year, Labour Day and the
+first three days of National Day. Lunar holidays (Spring Festival, Qingming, Dragon Boat,
+Mid-Autumn) must be added by hand.
+
+## HTTP surface
+
+The host half registers three exact, read-only routes on the DSH web server:
+
+| Route | Returns |
+| --- | --- |
+| `GET /api/consumption/turns?sessionId=<id>` | per-turn `{turn, hit, miss, out, time, model}` (log-length cached) |
+| `GET /api/consumption/account` | current provider/model + whether the key is configured |
+| `GET /api/consumption/balance[?force=1]` | `{ok, available, currency, total, granted, toppedUp}`; `is_available:false` renders a red “insufficient balance” |
+
+These routes are **unauthenticated**. If your DSH web server binds `0.0.0.0`, anyone on the
+network can read the balance and token figures; keep it on `127.0.0.1` unless you need otherwise.
+
+## Prompt for your AI agent (copy-paste)
+
+Paste this into Claude Code / Codex / DSH and let it do the install and verification:
+
+```text
+Install the DSH plugin "dsh-consumption-badge" into my web profile and prove it works.
+
+1. In $DSH_HOME/profiles/web run: `dsh plugin --profile web add dsh-consumption-badge`.
+   (For a local checkout use `dsh plugin --profile web add "file:<abs path to the package>"`.)
+2. Check `dsh --profile web --dump-config` contains exactly ONE `id: consumption-badge` row.
+   `dsh plugin add` also appends the package to `dsh.profile.bundles`; if that row does not
+   actually mount after the restart, move it: remove it from `dsh.profile.bundles` and add
+   `- insert: [{id: consumption-badge, name: 'dsh-consumption-badge'}]` to the profile's
+   `cordis.patch.yml` instead. Never leave both.
+3. Restart the DSH process (a browser refresh is NOT enough — host plugins are composed at boot).
+4. Verify the host half: `curl -s http://127.0.0.1:<port>/api/consumption/account` must return
+   `{"ok":true,...}`. Verify the client half:
+   `curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:<port>/plugins/dsh-consumption-badge/client.js`
+   must return `200`.
+5. Open any session and confirm the `⛽ <tokens> | ≈¥<cost> | peak|valley` pill in the assistant
+   action row; click it and confirm the modal shows the four cards, the dual-axis chart, the
+   balance, and that Esc closes it.
+6. Report which step failed and paste the boot log lines that mention `consumption-badge`.
+
+Rules while doing this: never write to the DSH credentials file yourself (ask me for
+DEEPSEEK_API_KEY), never bind a second server to the same port, and do not try to persist the
+plugin by "running" it — a session-scoped dynamic plugin always dies with the process.
+```
+
+## Notes for AI agents
+
+- This is a **profile-level** plugin: `package.json` carries `dsh.bundle.patch` and `dsh.client`
+  (`platform: web`). It cannot be shipped as a dynamic/session plugin — `harness.handle` and
+  `host.call` are dynamic-runner-only and do not exist for a bundled plugin; the client half talks
+  to the host half over the same-origin routes listed above.
+- The client bundle is hand-written in `window.__ModuleLoader__.load({id, factory})` form and only
+  `require("react")` — React must stay external (a second React instance breaks slot rendering).
+- `lib/index.js` imports nothing at all (no `@deepseek-ai/cordis`), so it does not depend on the
+  profile being able to resolve Cordis; it exports plain `name` / `inject` / `apply`.
+- Self-check without booting DSH: `node check.mjs` (46 assertions over the route contract and the
+  client bundle contract). It lives outside the published `files` list.
+
+## Known limitations
+
+- All amounts are **estimates** — price table, peak/valley rules and model detection can drift
+  from your actual invoice.
+- One chart point per turn; multiple steps in a turn are summed.
+- Balance parsing depends on DeepSeek's `/user/balance` response shape; failures only affect the
+  balance card.
+- The chart covers turns present in the session log fold (whole log), while the pill's total uses
+  the shipped `tokenUsage` projection — both are whole-session, but a heavily-compacted session may
+  differ by the tokens lost to compaction.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-consumption-badge —— bundle patch
+# 本插件作为 profile 的 bundle 层被挂载：profile 的 package.json 把它列进
+# dsh.profile.bundles 后，这一行 insert 就会把它插进配置树。
+# `name:` 必须与安装后的包名完全一致，否则表现为「装上了但界面上没有」。
+- insert:
+    - id: consumption-badge
+      name: dsh-consumption-badge