dsh-session-metrics

Session cost and billing metrics for the DSH Web GUI — what this conversation cost, what the
cache saved, and whether the current hour is peak or off-peak. Built as a companion to the shipped
stats pills, never a duplicate of them.

Why

The shipped stats pills report tokens and context, and stop short of money. That leaves three
questions unanswered, and the obvious answer to each is a lie:

A model with no rate card is not free. An unpriceable provider reads unpriced and shows its
tokens; a genuinely free model ships a card of zeros and reads a real $0.00. The two must not
render alike — unpriced means no card, and an unpriced pair is never rendered as a number.

A newly integrated provider arrives silently. DSH reports usage per provider and model; rates are
configuration. Integrate a provider before its rates are entered — the case that happened with
OpenRouter — and every figure for it is missing with nothing on the page saying why. The session
detail names the pair it observed with no card, and the tokens it used.

Peak pricing is invisible until it is a surprise. DeepSeek bills peak and off-peak at different
rates, in the provider's own timezone. Whether right now is peak is not something a user should
have to derive.

Agent Skills

Installing the plugin registers the session-metrics skill, so an agent can explain the figures
and reconfigure the rates without reading the source. Ask it what a session cost, whether a model is
priced, or how to add a rate card for a provider it has seen.

Quick Start

The plugin installs into your DSH profile by link — it is not published to npm, so the clone is
the source. Both routes end with a restart.

Option A — the script

git clone https://github.com/mrdhira/dsh-session-metrics.git ~/.dsh/plugins/dsh-session-metrics
cd ~/.dsh/plugins/dsh-session-metrics
./install.sh                 # builds, registers in your profile, runs pnpm install

It accepts --profile to target a profile other than ~/.dsh/profiles/desktop, --check to
report what would change without writing anything, and --remove to unregister.

Option B — the manual steps

1. Clone it somewhere stable (this path becomes your install path):

git clone https://github.com/mrdhira/dsh-session-metrics.git ~/.dsh/plugins/dsh-session-metrics
cd ~/.dsh/plugins/dsh-session-metrics

2. Build it. pnpm install runs the prepare script, which builds lib/** — the part DSH
actually loads. It is generated; never hand-edit it.

pnpm install

3. Register it with your profile — the dependency and the bundle name, with an absolute path:

{
"dependencies": {
"dsh-session-metrics": "link:/Users//.dsh/plugins/dsh-session-metrics"
},
"dsh": {
"profile": {
"bundles": [
"dsh-session-metrics"
]
}
}
}

4. Install the link, then restart DSH:

cd ~/.dsh/profiles/desktop && pnpm install

Nothing needs adding to cordis.patch.yml: the bundle declares its own Loader row.

> Restart, don't reload. The host half loads once per app process, so a host-side change needs a
> full quit and reopen (⌘Q, then reopen). A page reload does not pick it up. A client-side (UI)
> change needs the bundle toggled in the plugin manager.

Verify it is really working

A strip should appear below the composer with cost, saved and a peak indicator. If it does not:

• lib/v1/index.js exists — if not, pnpm install did not finish building;
• the profile's package.json names dsh-session-metrics in both dependencies and
  dsh.profile.bundles;
• DSH was restarted after installing.

An unpriced chip means a working install with no matching rate card — not a failure. See
Configure.

Configure

A fresh install needs no configuration. Rate cards ship for deepseek-account,
deepseek-official, netra-runtime and openrouter, so the cost chip works immediately. OpenRouter
ships only the models its own catalog marks free (the :free suffix and the free-models router)
at zero rates; its paid models deliberately carry no card, because DSH reports no prices for them and
a fabricated rate is worse than a named gap.

Rates are edited in the GUI: Plugins sidebar → dsh-session-metrics. The same table can be set
in your profile's cordis.patch.yml:

- id: session-metrics
name: dsh-session-metrics
config:
display: { currency: USD, primaryProvider: deepseek-account }
budget: { sessionUsd: 5, warnAt: 0.75 }
providers:
- id: my-router
models:
- model: some/model
rates: { flat: { cacheHit: 0.01, cacheMiss: 0.1, output: 0.25 } }
billing: { windows: [] }      # no peak concept

Rates are USD per 1M tokens. A model takes either a flat row or a peak row with
offPeak. A provider with no billing.windows is flat and shows no peak chip.

> A providers: list in your patch replaces the shipped cards rather than adding to them. Pin your
> own providers and the OpenRouter free cards stop shipping with them — add a card for each pair you
> need, or let Seen, unpriced name the ones you missed.

The full rate-card format, the shipped cards and the reasoning behind them are in
docs/pricing.md.

How it Works

Costs are derived from the Host's own tokenUsage projection — the same source the stats pills read
— so this plugin adds interpretation, not a second ledger. Cache savings compare each cache-hit token
against the rate that would have been paid on a miss, per the card in effect. Peak and off-peak
windows resolve in the provider's own timezone, holidays included, and the countdown is computed once
a minute while the detail view is open rather than on every render.

Two surfaces, one projection:

• the strip, below the composer: cost, cache savings, the peak state with your local time, the
  provider when it is not your configured primary, and budget progress;
• the detail, on click: the cost breakdown (cache-hit / miss / write / output), cache savings and
  blended rate, the rate window with a countdown, cost per step, cost per model when a session
  switched models, and the projections each figure came from.

The plugin deliberately does not render session token totals, cache-hit rate, context percentage,
turns, steps or tok/s — the shipped pills own those. docs/data-sources.md
records which projection feeds which figure, which is what keeps the two from drifting back into
duplication.

Requirements

• DSH with the Web GUI, and a profile you can edit (~/.dsh/profiles//).
• Node.js 22+ and pnpm to build from source. The built artifact needs nothing extra at
  runtime.

Development

pnpm install                  # deps + build (prepare)
pnpm run build                # rebuild lib/**
pnpm test                     # 111 tests: 105 pass, 6 skipped without a session log
pnpm run typecheck            # three projects: host, browser half, tests
pnpm run test:fast            # host logic only — the quick loop
pnpm run test:dom             # the UI half under jsdom
DSH_SESSION_LOG=.jsonl.zstd pnpm run test:replay   # replays a real session

src/host/*.ts         host half: config schema, projection, ledger, pricing  -> lib/v1/index.js
src/client/index.cts  browser half: strip, detail panel, pricing page        -> lib/v1/client.js
types/dsh.d.ts        the DSH surfaces this plugin uses (the app ships no .d.ts)
build.mjs             esbuild: ESM host half, CJS browser half + loader handshake
docs/                 authoring, data-sources and pricing notes

The six skipped tests are the replay ones; they need DSH_SESSION_LOG pointing at a real recorded
session. With one, the suite is 111/111.

lib/** is generated and never hand-edited. Build before you test: the tests import the built
artifacts, so a run against a stale build is green and wrong — pnpm test builds via pretest.

Testing and Validations

111 tests across twelve files. The host half is covered table-driven — every case names the rule it
pins, so a failure reads as a sentence — and the browser half mounts the real bundle under jsdom.

What the suite proves beyond "the code runs":

• the freshness gate (build.test.ts): every source module has an artifact, no artifact predates
  its source, and the entrypoints main/exports name actually exist. This exists because five test
  files once validated stale pre-port lib/*.js that were no longer shipped — green, and wrong.
• non-vacuity: a new test is proven by mutation probe, not by passing. Deleting the badge's
  subject gate fails 2/14; reverting the calendar default fails one named test.
• memory discipline: two defects once drove a machine to ~170 GB RSS, so the suite runs through
  scripts/guard.mjs, which watches the whole process tree and kills it past the cap (exit 124 —
  bisect, never raise it). A failing assertion must never take a DOM node as its actual value:
  compare primitives (assert.ok(node === null)), because inspecting a React node walks its fiber
  tree and allocates without bound.

Measured on Node v24: host tests peak ~70 MB, the DOM file ~180 MB, and the full suite with a real-log
replay 277 MB under a 1 GB limit.

Contributing

One author: Dhira Wigata. Every commit is authored and committed by him, and CI re-checks the
whole history for a single identity and for machine-attribution trailers — so --no-verify locally
does not get a commit past CI. Signed-off-by: is fine. See AGENTS.md for the gates a
change must pass: build, typecheck across three projects, and the suite.

Issues and pull requests are welcome.

What it looks like

The strip as it docks under the composer, at the width the app actually gives it: DSH's own
computeColumns() resolves a 1440×900 window to a 280px sidebar and a 1160px centre column, and
that is the canvas below. Every colour is one of the app's theme tokens.

The detail popover behind the trigger — cost breakdown, saving breakdown, per-model rows, and the peak
window with its countdown.

Both come from scripts/capture-panel.mts, which renders the real bundle through
test/harness.ts — the same path the DOM tests take — injects the real stylesheet the bundle
itself ships, and resolves the --dsw-* tokens out of the installed app.asar. Nothing is mocked and
no colour is hand-picked. Run it with:

node ~/.dsh/scripts/guard/guard.mjs --limit-mb 2560 -- \
node --max-old-space-size=384 scripts/capture-panel.mts

One honest gap: the popover is captured standalone, centred by a layout wrapper, rather than
anchored under the strip. Its left/bottom come from a live getBoundingClientRect() of the docked
trigger, and the headless renderer has no layout engine to produce one — so its content, width and
styles are real, and only the frame around it is not.

There is no flow to draw

This is a metrics panel, not a pipeline: the strip and the popover are two projections of one
already-complete figure. Costs are derived from the Host's own tokenUsage projection, savings compare
each cache-hit token against the miss rate on the same card, and the peak state is a clock read against
the provider's window — all computed in the browser half on render. No queue, no stages, no hand-off,
and no ordering a diagram would add information to. A flow diagram here would be decoration, so there
is none; the data path is the table in docs/data-sources.md instead.

LICENSE

MIT © Dhira Wigata