description: "dsh-price-monitor: a dsh-better-sidebar tab that prices a DeepSeek Harness session's provider-reported token usage."
kind: "user-guide"
dsh-price-monitor
Session cost monitoring for DeepSeek Harness: a host-side session projection
folds the durable log into a per-attempt token ledger, and a
dsh-better-sidebar tab prices
that ledger with an official or hand-entered plan.
Requirements — read this first
This plugin has no user interface of its own. It renders entirely as a tab of
dsh-better-sidebar, which
must be installed and mounted first. Without it:
- there is no place for the cost view to appear — this package registers a
single sidebar tab and a plan-settings panel, nothing else;
- the client half refuses to activate, and says so
(
dsh-price-monitor requires Better Sidebar features: pluginSettings, stateSubscription),
rather than loading a half-working panel.
| Requirement | Why |
|---|
DeepSeek Harness with the web profile | the plugin ships a Host half (a session projection and an HTTP route) and a browser half |
| dsh-better-sidebar ≥ 0.18.0, mounted and enabled | the tab, the settings panel, the plan catalog's storage, and the projection read all come from its service API (ctx.betterSidebar, stateSubscription, pluginSettings) — see Install |
| A plan for the rates you want to see | the selected plan prices the session; without one, every request is listed as unpriced rather than guessed |
The host half (the token ledger) works without the sidebar, but nothing reads
it: the ledger has no UI besides that tab.
What it shows
- Total cost for the current session at the selected plan's rates, with the
exact three-bucket split (cache miss / cache hit / output) in both tokens and
USD.
- Per-turn list: every turn with its tokens and cost, expandable to each
billed request attempt — including attempts that retried, switched model, or
cannot be priced.
- Plan card with the selected plan's rates and a same-tokens comparison
across every saved plan.
- Partial honesty: an attempt whose usage never arrived or failed
validation, whose cache buckets cannot be separated, or that reported
cache-write tokens the plan has no rate for is excluded from the money and
listed with its reason. Token counts, being provider-reported facts, are still
summed and shown: unknown cost never blanks a known count, and unknown is
never shown as zero.
Architecture
host priceMonitorUsage session projection ← the only fact source
└─ one row per (turn, step, attempt): startedAt/settledAt, provider,
model, the four DSH token buckets, completeness
client price tab (dsh-better-sidebar)
├─ reads the projection through ctx.sessions.binding(id)
├─ prices it with decimal.js under pluginSettings['price-monitor']
└─ official refresh: POST /price-monitor/api/official-pricing
Three properties follow from that split, and each is covered by tests:
- Complete history — the ledger comes from the whole persisted log, not
from the client's paged event window.
- No double counting — pricing never re-derives tokens; it consumes the
exact provider-reported buckets. The fold mirrors the harness's own
deriveTurnTokenUsage and is cross-checked against it for every complete
turn.
- Re-pricing is free — plans live in the sidebar's settings, so switching
a plan re-prices without touching the session log.
Token bucket semantics
DSH's TokenUsage buckets are disjoint: inputTokens is uncached input
only, and DeepSeek's adapter subtracts cache hits out of prompt_tokens
before writing it. Pricing therefore multiplies each bucket by its own rate and
never computes prompt_tokens - cacheReadTokens. outputTokens already
includes reasoning tokens, so reasoning is never billed twice.
Pricing plans
Rates are USD per million tokens stored as decimal strings; every product and
sum stays a Decimal until display.
| Plan source | Editable | Created by |
|---|
official | no — duplicate it first | the bundled snapshot, or an official refresh |
manual | yes | the settings panel |
How a session is priced
The selected plan is the whole pricing basis. It prices every attempt of
the session, so switching a plan moves the hero total, the three-bucket
breakdown, the per-turn rows, and the comparison list together — the reason to
switch is exactly "what would these tokens cost at other rates", and the model
and provider that produced them are what the substitution replaces. Nothing
about an attempt's route gates an amount: a request whose model no plan names, a
request that ran on another gateway, and a request with no route recorded at all
are all priced at the selected plan's rates.
Only the token facts can leave an attempt out of the money: usage that never
arrived or failed validation, cache buckets that cannot be separated, and
cache-write tokens a plan has no rate for. Their tokens are still counted, and
the hero switches to "known cost" with the reason tally, so an unknown amount
never becomes a zero.
A plan's declared rate period (effectiveFrom / effectiveTo) is a label for
the plan card — when those rates applied — and never a gate: the selected plan
prices the whole session whatever dates its attempts fall on. The bundled
snapshot omits a start deliberately, because a fetch observes today's rates
rather than learning when they began.
Peak/off-peak uses each attempt's UTC start time: Monday–Friday, 01:00–04:00 and
06:00–10:00 UTC are peak (left-closed, right-open), and a plan without a peak
band prices everything at its single rate. The bundled snapshot is dated
2026-09-10 and shows its source link in the UI; it prices the two models the
page lists — the flash model and the pro model — with one flash price covering
the ids that model has been listed or reported under (deepseek-flash,
deepseek-v4-flash, deepseek-v4-flash-vision-exp).
Stored settings carry a schemaVersion. A readable version 1 blob — which also
held a calculation mode and a model-alias map — is upgraded in place, keeping
the user's plans and selection; both fields are gone because neither can change
an amount under a single pricing basis.
Official price refresh
The client never fetches the upstream page. It POSTs to the plugin's host
route, which:
- requires the browser-trust fence (Host header must be loopback or a
configured trusted authority;
cross-site and mismatched Origin are
refused) and POST only;
- fetches one hard-coded URL (
https://api-docs.deepseek.com/quick_start/pricing/)
— a client payload cannot change the target, redirects must stay HTTPS on
that one host, and the body is capped at 256 KiB and must be HTML;
- parses the page strictly: model header, the three priced categories across
both bands, the peak = 2 × off-peak relation, and the peak-window footnote.
Any structural change fails the whole import (HTTP 502) and the caller keeps
the last good catalog;
- returns a per-field diff. The user confirms in the tab before anything is
written, and applying appends new immutable official versions (fresh ids) —
previous versions stay for historical comparison.
Install
Install and mount dsh-better-sidebar first — this plugin's tab appears in
that sidebar's + menu, and its plan settings appear in that sidebar's
Side card settings page. Then install this plugin:
# 1. the sidebar this plugin renders inside (skip if you already have it)
dsh plugin --profile web add dsh-better-sidebar
# 2. this plugin
dsh plugin --profile web add dsh-price-monitor
Both commands append a bundle to the profile and restart-time mount; restart
DSH after installing (the Host halves changed), then open the sidebar's +
menu and pick Session cost.
Development install (from this checkout)
cd dsh-price-monitor
pnpm install
pnpm run build # tsc emits lib/types, tsdown emits lib/index.js + lib/client.js
Then point the profile's sidebar plugin at the built package:
# ~/.dsh/profiles/web/package.json
"dependencies": {
"dsh-price-monitor": "link:E:/Code/my_code/dsh_price_monitor/dsh-price-monitor"
}
cd ~/.dsh/profiles/web && pnpm install
The package's own cordis.patch.yml (dsh.bundle.patch) mounts the host half
once the bundle is in dsh.profile.bundles; for a link: install add the
bundle name there as well:
"dsh": { "profile": { "bundles": [ "...", "dsh-price-monitor" ] } }
Then restart DSH and hard-refresh the browser. The tab appears in the
sidebar's + menu as Session cost; its gear opens the plan settings.
Restart the host after any rebuild, including client-only edits: the client
artifact is served from /plugins/<package>/client.js with a revision derived
from its bytes, and a link:ed package outside the loader's watched workspace
is not re-read while the host runs — a rebuilt lib/client.js keeps being
served from the host's in-memory copy until it restarts.
Published install
dsh plugin --profile web add dsh-price-monitor
The same sidebar-first rule applies: with no mounted dsh-better-sidebar the
client half throws at activation instead of silently doing nothing, so check
that the sidebar itself is working before filing a bug here.
Privacy and network behavior
- Reading the ledger and pricing it are entirely local; nothing is uploaded.
- The only outbound request is the official-pricing refresh, which the user
triggers explicitly and which fetches one public documentation page.
- Plan settings live in the sidebar's own preferences document
(
pluginSettings['price-monitor'].catalog), i.e. alongside the user's other
sidebar settings; the plugin writes nothing into session logs.
Configuration
No cordis.yml configuration: the plan catalog is user data, edited in the
settings panel. The bundled official snapshot is the offline default.
Development notes
pnpm run typecheck, pnpm run test, pnpm run build.lib/ is committed, so a git install (dsh plugin add github:<owner>/dsh-price-monitor)
needs no build step. Rerun pnpm run build and commit lib/ together with any
source change.- The client half is a ModuleLoader closure factory (
format: 'cjs' wrapped in
window.__ModuleLoader__.load), because the harness evaluates it as a classic
script at /plugins/dsh-price-monitor/client.js; only the harness's browser
module table may stay external, so zod and decimal.js are inlined.
- Styles are injected as one
<style> element from src/client/styles.ts
rather than a *.module.css import: tsdown does not compile CSS modules
without an extra plugin, and every class carries a dpm- prefix so one
global sheet cannot collide. Colors come only from DSH theme tokens.
- The tab writes its catalog through the sidebar's own settings route with the
same whole-
pluginSettings patch its client sends, serialized through one
promise chain so two quick edits cannot interleave.
Tests
| File | Covers |
|---|
tests/usage-ledger.spec.ts | the fold: attempt lifecycle, retries, validation, contradictions, reference stability, cold/live parity, and cross-checks against the harness's deriveTurnTokenUsage |
tests/pricing-engine.spec.ts | peak boundaries, the selected plan as the sole basis (route, model, and rate period never gate an amount), switching plans reprices every layer, token facts under partial pricing, decimal exactness, schema rejection, and the v1 upgrade |
tests/official-pricing.spec.ts | both saved page fixtures (three-column and the renamed two-model layout) parse exactly; changed amounts, categories, headers, malformed ids, or footnote windows fail |
tests/trust-fence.spec.ts | loopback/trusted hosts pass; cross-site, opaque, and mismatched origins fail |
tests/client.spec.tsx | activation and the feature gate, catalog reads (including the v1 upgrade), the hero total equal to the sum of the turn rows, and a plan switch repricing hero, breakdown, and rows |
tests/client-interaction.spec.tsx | expanding a turn reveals each attempt; clicking a plan writes the catalog and reprices the rendered tab; a failed write surfaces |
tests/built-artifacts.spec.ts | the built entry points exist and behave; the client bundle is a valid loader factory; the route over real HTTP refuses GET/cross-site/foreign redirects and returns a candidate plus diff |
