dsh-deepseek-cost-watch
A DeepSeek Harness profile bundle that puts the
DeepSeek off-peak schedule, the remaining account balance, and a live cost estimate
into the Web UI.
It replaces two throw-away dynamic plugins with one permanent, installable package: no bundler,
no build step, no dependencies, two small JavaScript files.
What it does
1. Off-peak badge (frame-wide overlay)
A floating card in the bottom-right corner of the app:
┌─────────────────────────────────────┐
│ ● DeepSeek off-peak – │
│ [−50%] Discount active │
│ Ends in 1h 42m 07s │
│ Balance $8.28 │
│ ─────────────────────────────────── │
│ Peak UTC: Mon–Fri 01:00–04:00 · │
│ 06:00–10:00 │
│ Local time (UTC+02:00): │
│ 03:00–06:00 · 08:00–12:00 │
│ Outside those windows every model │
│ costs half. │
└─────────────────────────────────────┘
- Live state — green (
−50%) during off-peak, amber (PEAK) during peak hours, refreshed
once a second.
- Countdown to the next peak/off-peak flip.
- Balance — the credit left on the DeepSeek account, straight from the official
GET /user/balance endpoint. Hover for the granted / topped-up split and the read time; click
the row to refresh it on the spot.
- Schedule in both zones — the fixed UTC windows plus the same windows shifted into your
browser's timezone, including the
(+1d) marker when a window crosses midnight locally.
- Collapsible — press
– to shrink it into a PEAK · 18m 04s / OFF-PEAK −50% pill; click
the pill to expand it again.
2. Cost estimate (under the composer)
Beside the shipped token counter, above the composer:
- Collapsed: a coloured dot plus the estimated spend for the open Session —
● ≈ $0.1414.
Green means the request you are about to make is billed off-peak, amber means peak.
- Expanded (click): the full breakdown, in normal page flow, so nothing overlaps the
composer or the badge:
Estimated total $0.1414
Balance $8.28
Peak (01-04, 06-10 UTC, Mon-Fri) $0.1414 · 5.95M tok
Off-peak $0.00 · 0 tok
Uncached input 114.46k tok
Cache read (hit) 5.77M tok
Output 60.35k tok
Model DeepSeek-V4.1-Flash · $0.1414
Right now peak · changes at 10:00 UTC
Estimate from the official DeepSeek rates (2026-09-15): cache hit /
cache miss / output, with off-peak at half the peak rate. Not a billed amount.
The estimate is history-aware: every billed request in the Session log is priced with the card
that was in force when that request happened, so a Session that spans a tier change is split
correctly between peak and off-peak instead of being priced entirely at today's rate.
3. Balance
The same figure the DeepSeek platform shows on its top-up page, without leaving the app:
- Read by the Host, never by the browser: the API key stays in the Host process and is sent
only to
api.deepseek.com.
- Resolved exactly like the model route does — the stored credential (
DEEPSEEK_API_KEY, the
ref the Models page writes) and, failing that, the launching environment.
- Refreshed once on plugin activation, every 5 minutes, and on demand when you click the row.
The Host caches an answer for 60 seconds, so several browser tabs never multiply the calls.
- Degrades instead of breaking: no credential renders
no API key, an unreachable API renders
unavailable, and both explain themselves in the tooltip. Low credit (is_available: false)
turns the amount amber.
Requirements
- DeepSeek Harness with the
web profile (a version that ships dsh plugin and dsh.bundle
profile bundles — 0.1.5-rc or later).
pnpm on PATH (dsh plugin forwards to it).git on PATH when installing from GitHub.
Install
From GitHub:
dsh plugin --profile web add github:Webificio/dsh-deepseek-cost-watch
From a local checkout (after replacing owner/repo with your own fork, the same command works
against your fork):
dsh plugin --profile web add /absolute/path/to/dsh-deepseek-cost-watch
Either command installs the package into the web profile and appends it to
dsh.profile.bundles automatically (the package declares dsh.bundle.patch, so dsh plugin
recognises it as a profile layer).
Then restart the profile — a bundle is composed at profile boot, so stop the running
dsh web and start it again:
dsh web
Reload the browser page. You should see the off-peak card in the bottom-right corner, and the
cost line appear in the composer dock as soon as the open Session has billed at least one request.
Verify the install
cat "${DSH_HOME:-$HOME/.dsh}/profiles/web/package.json"
dsh-deepseek-cost-watch must appear in dsh.profile.bundles. If it does not, the plugin was
installed as a plain dependency; re-run the add command and read pnpm's output.
Uninstall
dsh plugin --profile web remove dsh-deepseek-cost-watch
Restart the profile afterwards. Both occupants and both Host routes disappear with the package.
How it works
One profile row, two halves of the same package:
| Half | Entry | What it contributes |
|---|
| Host | lib/host.js (main) | Two read-only Fetch routes on the Connection carrier: GET /api/deepseek-cost-watch/report?sessionId=… (folds the live Session log into a cost estimate) and GET /api/deepseek-cost-watch/balance (reads the account credit with the stored key). |
| Browser | lib/client.js (exports["./client"]) | A Cordis client plugin claiming two slots: shell.overlay (the badge with the balance row) and conversation.composer.dock (the cost line). |
browser (client.js) host (host.js)
──────────────────── ──────────────
shell.overlay ─┐
off-peak badge │ in-process: local peak/off-peak math (no round trip)
balance row │
conversation. ─┤
composer.dock │
cost line ─────────┤ fetch ─────────▶ GET /api/deepseek-cost-watch/report
│ ctx.sessions.get(id).snapshotEvents()
│ → foldUsage() → JSON
└ fetch ─────────▶ GET /api/deepseek-cost-watch/balance
ctx.credentials.resolve('DEEPSEEK_API_KEY')
→ api.deepseek.com/user/balance → JSON
The fold lives on the Host on purpose: only the Session log records when each request was
billed, while the browser's tokenUsage projection carries aggregate token totals with no
timestamps. The balance is read on the Host for a different reason: the API key must never reach
the browser. The overlay's live clock needs no Host round trip at all, so it recomputes locally
every second from the published schedule.
Everything the plugin registers — both Fetch routes, the stylesheet, the balance poll, and both
Slot occupants — is owned by the plugin's fiber, so stopping, updating, or removing the package
withdraws all of it.
Files
dsh-deepseek-cost-watch/
├── package.json # name, exports, dsh.bundle.patch, dsh.client.platform
├── cordis.patch.yml # the one profile row this bundle inserts
├── lib/host.js # Host half: rates, schedule, session-log fold, balance, both routes
├── lib/client.js # Browser half: hand-written module-loader bundle
├── test/smoke.mjs # dependency-free checks for both halves
├── README.md
└── LICENSE
Balance, credentials and endpoints
| Setting | Default | Where |
|---|
| Credential ref | DEEPSEEK_API_KEY | stored credential (Models page) or the launching environment |
| API base URL | https://api.deepseek.com | DEEPSEEK_BASE_URL, the same variable the model adapter reads |
| Balance endpoint | GET /user/balance | — |
| Host cache | 60 s | BALANCE_TTL_MS in lib/host.js |
| Browser poll | 5 min, plus click-to-refresh | BALANCE_REFRESH_MS in lib/client.js |
The key is used for exactly one request: Authorization: Bearer <key> against the configured base
URL. It is never logged, never returned by the route, and never sent to the browser.
Prices, and how to update them
The rate tables live at the top of lib/host.js as USD per 1,000,000 tokens,
written [off-peak, peak] per bucket (cache hit, cache miss, output):
export const RATE_TABLES = [
{
id: 'deepseek-flash',
name: 'DeepSeek-V4.1-Flash',
models: ['deepseek-flash', 'deepseek-v4-flash'],
cacheHit: [0.003, 0.006],
cacheMiss: [0.15, 0.3],
output: [0.6, 1.2],
},
]
RATE_AS_OF and RATE_SOURCE are printed in the expanded panel, so a stale table is visible
in the UI rather than silent.- Update the numbers when DeepSeek publishes new pricing, then restart the profile.
- Only
deepseek-official routes are priced. Anything else is counted and reported as
unpriced rather than guessed at.
- The schedule (
PEAK_WINDOWS) is UTC: Monday–Friday 01:00–04:00 and 06:00–10:00, with off-peak
at half price at every other hour.
- The number shown is an estimate, not an invoice: it uses the list price of the configured
model, while credits, discounts, or a provider-side price change are invisible to it.
Development
There is no build step. Edit lib/host.js or lib/client.js and restart the profile.
npm test # node test/smoke.mjs — no dependencies
The smoke test prices a synthetic Session log across both rate cards, exercises the report route
(200 / 400 / 404), drives the balance route against a stubbed DeepSeek API (success, cache,
?refresh, HTTP error, unreachable, missing credential), then loads the browser bundle with a
stub module loader and asserts that it registers the module id, claims both Slot occupants,
injects the stylesheet, polls the balance, and renders the badge with the remaining credit.
lib/client.js is a hand-written bundle in the Harness's client module-loader format
(window.__ModuleLoader__.load({ id, factory })), which is why the package needs no bundler.
Two details are load-bearing:
- the registered module
id must equal the package name in package.json, and
- the bundle must stay self-contained —
React comes from the runtime's module table
(require('react')), and nothing else is imported.
Limitations
- The cost line appears only for Sessions the Host still holds in memory, i.e. the conversation
you have open. Cold or archived Sessions are not re-read from disk.
- The estimate covers billed assistant requests in the Session log; subagent Sessions are priced
in their own conversation.
- The browser half targets the Web profile (
dsh.client.platform: "web"); TUI and headless
profiles load the Host routes only.
- The balance needs outbound network access to the DeepSeek API from the Host process; behind a
proxy, set
DEEPSEEK_BASE_URL to the reachable origin. When it cannot be read, the row says so
and the rest of the plugin keeps working.
- The balance is the account's credit, not a per-Session figure, and it is only as fresh as its
last read (5 minutes, or one click).
License
MIT — see LICENSE.
