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.

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 money, in the plan's own currency.
• Per-turn list: every turn with its tokens and cost, expandable to each billed request — including requests that retried, switched model, or cannot be priced. One request is one model call, i.e. one harness step, and the loop numbers a turn's steps 1..N, so a row reads "request N". A retried request keeps that number and gains "retry N" rather than appearing as an extra step.
• 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:

1. Complete history — the ledger comes from the whole persisted log, not from the client's paged event window.
2. 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.
3. 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 per million tokens, stored as decimal strings; every product and sum stays a Decimal until display.

The bundled catalog is the flash model's published price history — one plan per era, all in CNY, with the era in force selected:

A refresh replaces the official plan with the era the page currently describes: one plan carrying one rate table per model the page lists, so a retired model billed at its successor's rates is expressed as a group naming both ids.

Currency

Official pricing is CNY by default: both the bundled snapshot and the refresh route read DeepSeek's Chinese pricing page, which prints the primary published numbers in yuan. The English page prints the same rates as a rounded USD conversion of them (1 USD ≈ 6.818 CNY on the 2026-09-10 snapshot: flash is ¥0.02 / ¥1 / ¥4 in Chinese against $0.003 / $0.15 / $0.6 in English), and this plugin never converts between the two.

A plan therefore carries the currency its publisher printed — CNY for the official plans, and whichever currency a manual plan was saved in — and an amount always reads in the currency of the plan that produced it. $0.15 and ¥1 are never silently added together. The same rule governs the comparison list: rows of different currencies still list their totals, but no percentage is shown between them, because a ratio across currencies would be meaningless.

Add a manual plan in USD if you account in dollars, and copy an official plan into a manual one to restate it in the other currency. A plan's modelIds never affects an amount, so a USD plan prices any session just as a CNY one does.

Price phases

DeepSeek changes these rates over time, so the same session can be compared across phases by saving one plan per phase and switching between them; the comparison list then shows every phase's total for the very same tokens. Record when each phase applied in its rate period (effectiveFrom / effectiveTo) — that period is a label for the plan card and never gates pricing, so the selected plan prices the whole session whatever dates its attempts fall on.

A superseded phase knows when it ended without knowing when it began, so either end of the period may be filled in on its own.

How a session is priced

The selected plan is the whole pricing basis, and a plan is an era: the rates one provider charged for a set of models over a window. 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 under another era", and a session that switched models mid-way is still priced model by model.

Within a plan, each attempt is priced by the group its own model belongs to:

• a group that names the model prices it;
• a model no group names (a renamed id, a model the era never listed, an attempt with no route recorded) is priced by the plan's first group, the era's headline rates, and the attempt row says priced as <model> so the substitution is visible rather than silent.

Nothing about a provider gates an amount either: a request that ran on another gateway is priced the same way. Only the token facts can leave an attempt out of the money.

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:

1. 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;
2. fetches one hard-coded URL (https://api-docs.deepseek.com/zh-cn/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;
3. parses the page strictly: the model header, the three priced categories across both bands, the peak = 2 × off-peak relation, and the peak-window footnote (the page states it in Beijing time; the schedule stores the equivalent UTC windows). Any structural change fails the whole import (HTTP 502) and the caller keeps the last good catalog;
4. 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