dsh-cost-stats

Money on the screen for the DeepSeek Harness web GUI: a cost pill under every completed turn, and a Cost tab next to the chat and trajectory views with charts, ratings and an interactive timeline. DSH reports tokens and never a monetary amount, so this plugin does the arithmetic against a local price table — the numbers are an estimate, not a bill.

Nothing upstream is patched: the plugin registers into the official slot, session-source and locale registries, so it survives DSH upgrades and uninstalls by removing one row.

What you get

In the chat — a flat, right-aligned pill in the message action row, styled like the shipped Used N tokens item next to it:

≈ $.6217   ⚙$.4698   🧠$.0430   👁$.1519

The icons are the categories, the numbers are what each kind of action cost (see below). Click it for the full breakdown: bucket table (uncached input, cached input, cache write, output, of which reasoning), model, turn number, wall time, TTFT and tok/s.

Under the composer — the same four numbers for the whole session, sitting right after the shipped stats strip (steps, tok/s, tokens, cache hit).

The Cost tab (order: 20, so it lands right after the action graph) contains:

• KPI cards: cost of the loaded turns, whole session, requests and average cost per request, reasoning share, cache hit %, tok/s, TTFT, turn wall time;
• per-turn token and cost columns, a spend-composition donut, time split and context composition;
• what each action costs — tools / reasoning / reading and analysis, with request counts, tokens, money and share;
• ratings: most expensive turns, tools by calls and time, most expensive requests with their model, models by cost;
• an interactive timeline (see below);
• the price table the whole thing is computed with.

What each action costs

Every model request is attributed to exactly one category by what that request did:

A request's cost lands in one category, so the shares always add up to the total. The read list lives in READ_TOOLS at the top of lib/client.js — MCP names are normalised, so mcp__some-server__Snapshot counts as snapshot.

The interactive timeline

Wheel zooms around the cursor, dragging pans, double click (or the Reset button) returns to the full range. A step selector offers 10 s / 1 min / 5 min / 15 min; rates are always normalised to a minute, so the unit never changes. Hovering any step shows its own numbers. The line above the plot summarises the visible window: range, requests, window cost, average rate, peak rate and how many requests fall outside it.

Geometry is one SVG with preserveAspectRatio="none" and all readable text lives in HTML layers on top — text inside a stretched SVG would be distorted. The wheel listener is attached natively with { passive: false }, because React's own onWheel is passive and preventDefault there is ignored (the page would scroll instead of the chart zooming).

Pricing

PRICES at the top of lib/client.js is four numbers per model, in USD per million tokens:

miss  — uncached prompt input
hit   — prompt input served from the provider cache
write — prompt input written into the provider cache
out   — completion output (reasoning tokens are a SUBSET of out, so they are not added twice)

The table ships with published DeepSeek rates on the prompt/output sides and hit at zero. That zero is deliberate: auditing a real, long-lived DSH corpus (tools/audit-usage.mjs) showed ~99.4 % of all prompt tokens arriving as cache hits, and pricing those at a published cache rate overshot the provider's own bill by an order of magnitude — cached input is evidently not charged on that plan. If yours is, put the real number in hit and every total moves with it.

Install

The plugin is a normal DSH client package. Put it anywhere, then add it to a web profile:

// ~/.dsh/profiles/web/package.json
{
  "dependencies": { "dsh-cost-stats": "file:<path to this checkout>" },
  "dsh": { "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-cost-stats"] } }
}

dsh plugin --profile web add "file:<path>" does the same thing and needs pnpm on PATH. A bundle list is composed at boot, so a newly added bundle shows up after a restart; edits to lib/client.js afterwards are picked up by dsh-client-hmr (it polls the bundle's mtime and size) without any restart.

If you would rather not touch the bundle list, mount the row from the profile's own live-reloaded patch layer instead — it composes at boot all the same, and reloads live:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: cost-stats
      name: dsh-cost-stats

Tools

node tools/smoke.mjs         # 96 assertions: folding, pricing, attribution, rendering, hooks
node tools/audit-usage.mjs   # independent audit straight out of the durable session logs

smoke.mjs renders the plugin against a miniature React and mock shell services, so it runs with no browser: it covers the cost folds, the category attribution, the money formatting, both seats the pill can render into, and — because both have already bitten once — that no component changes its hook count between data states.

audit-usage.mjs is the ground truth check. It reads $DSH_HOME/sessions/*/session.v3.jsonl.zstd (each file is a stream of independent zstd frames), sums the provider-reported usage, prices it with the same table, and reports per model, per session and in total. Useful flags:

node tools/audit-usage.mjs --session <id-prefix>   # one session
node tools/audit-usage.mjs --target <bill>         # solve the implied $/M, and print a ready table
node tools/audit-usage.mjs --root <dsh-home>       # read another DSH home

It makes no model calls — it only reads logs and does arithmetic, so running it costs nothing.

Limitations

• An estimate, not an invoice. Token counts come from the provider; the money comes from the local table.
• Money is only shown where the cost is actually known: an exact per-turn accounting, or a turn rebuilt from its own requests (marked ≈). Otherwise nothing is rendered rather than a made-up number.
• The report covers the loaded history window; the "whole session" figures come from the host's own token projection, priced with the effective tariff of the loaded turns.
• Timestamps are the request start times from the log, so a long request is attributed to the minute it began.

Notes for plugin authors

NOTES.md collects what was learned writing this against DSH's client-plugin API: the module format, the four slot kinds (and why chain is not a list), how session-scoped hooks reach a component, which conversation targets carry usage, and the React/scroll traps that only appear after a page reload.

License

MIT — see LICENSE.