dsh-billing-glass — Liquid-Glass Billing Overlay

English | 中文

A billing overlay plugin for the DeepSeek Harness Web GUI: a liquid-glass capsule
pinned to the bottom-right corner showing the provider balance; click to expand a full
billing card (session cost, daily spend, token-bucket breakdown, provider list).
DeepSeek-first, with an extension point for more API providers.

Features

• Always-on glass capsule: status dot + provider name + balance at a glance; click
  to expand. The expanded card's header is draggable (position stored in localStorage;
  it can be dragged anywhere on the page with no bottom dead zone). The card disables
  horizontal overflow — no horizontal scrollbar needed to reach content.
• Fresh data: the client polls every 10s; the DeepSeek balance cache TTL is 10s
  (other providers 60s); official daily spend is cached for 5 minutes; window focus, tab
  visibility change and card expansion refresh immediately, and the manual refresh button
  force-refreshes the current provider balance via POST.
• Liquid-glass material: backdrop-filter frost + translucent theme colors +
  specular highlight border + refraction sheen layer + soft float shadow; follows the
  --dsw-* light/dark theme automatically.
• Per-message cost badge: each assistant message's action bar shows a small cost
  chip (hover for the input/cache/output token split and model).
• Model series tag: the capsule and card show a short alias for the current model —
  DeepSeek Pro/Flash, Moonshot K2.5/K3, GPT 5.6-Sol/5.6-Terra/5.6-Luna, Claude
  Opus-4, Gemini 2.5-Pro, Qwen 3.7-Max, GLM 5.2; long tags ellipsize instead of
  stretching the card.
• Spend ledger & stats: an append-only JSONL ledger
  (storages/billing-glass-ledger.jsonl, idempotent, debounced appends, periodic
  compaction; the legacy billing-glass-ledger.json is migrated automatically; bad
  lines and partial tails are detected at startup, repaired and surfaced as a degraded
  warning). The expanded card shows today / this month / all-time totals, bucketed by the
  browser's IANA timezone so a UTC server does not shift the day boundary. costUsd is
  the only aggregation base; display uses costNative + nativeCurrency — the ambiguous
  single cost field is gone.
• Session cost: every assistant/message is priced against the official price
  policy (validity windows included, plus the 2026-08-17 peak/valley schedule). Live and
  replay share one canonical attribution pipeline (header > source) and are merged with
  messageId dedupe; full persistent-log replay (including pre-install history) + live
  fallback. Hover ⓘ for the tokens × unit price = subtotal formula.
• Unknown models fail closed: a model missing from the catalog (catalog lag, alias
  rename, brand-new model) is never silently priced at zero — the message is marked
  unpriced, the card and spend stats expose unpricedCalls: N, and the ledger stores
  priced: false.
• Daily spend (official only): the row appears only when
  DEEPSEEK_PLATFORM_TOKEN is configured. Without it the row is hidden — a
  balance-delta estimate would be confused by top-ups/refunds, so it is no longer a
  display source.
• Pricing sync check (button): the card's "plan" row has a ↻ verify pricing
  button that pulls the official pricing source of only the currently displayed
  provider and compares it against the built-in policy chain → ✅ synced / ⚠ drift
  found (details listed, page snapshot saved to
  storages/billing-glass-pricing-snapshot.html for the assistant to analyze) /
  unparseable (page changed; guided back to chat). 60s debounce.
• Multi-provider auto-switching: the card follows the provider in current use —
  the session's latest request/header provider > the harness-configured active
  provider (Settings → Models, agent-default-model) > the registry's first entry
  (DeepSeek-first). Click any provider in the bottom list to inspect it manually, click
  again to restore auto-follow; the configured active provider carries an "active"
  badge, providers without a configured key a "not configured" marker.
• Plan / fee system: each provider declares its plan (token pay-as-you-go /
  subscription); the "plan" row shows the billing mode + the current price tier
  (standard / peak / valley).

• Daily spend (official, optional): without DEEPSEEK_PLATFORM_TOKEN the row is
  hidden. With it, the card shows the exact official consumed value:

  1. Sign in at https://platform.deepseek.com, open DevTools → Console, run
     JSON.parse(localStorage.getItem('userToken')).value
  2. Add the result to ~/.dsh/.credentials.yaml:
     DEEPSEEK_PLATFORM_TOKEN: <token>
  3. Refresh the page; the card's "today consumed" row appears with the official
     figure. Expired tokens or API failures hide the row rather than falling back to a
     misleading balance-delta estimate.

Known limitations

• "Daily spend" is official-only: the row is hidden unless
  DEEPSEEK_PLATFORM_TOKEN is configured. A balance-delta estimate is no longer
  displayed because top-ups/refunds make it unreliable.
• Session cost and spend stats are locally computed, not a provider invoice: they
  are priced from the plugin's built-in official price tables and message tokens, and
  may differ slightly from the final platform bill (pricing moment, rounding,
  peak/valley interpretation).
• Spend stats only cover messages the plugin has seen: the current session can be
  replayed from the persistent session log (including pre-install history), but other
  historical sessions that the plugin never processed are not in the local ledger.
• Unknown models fail closed: a model missing from the catalog is marked unpriced
  rather than priced at zero, so displayed totals may understate the real bill; re-run
  scripts/sync-providers.js or provide a pricing scheme to close the gap.
• Some providers have no public balance endpoint: their balance shows "—", though
  session cost is still priced from the catalog.
• The price catalog can lag: non-DeepSeek prices come from the harness built-in
  pi-ai catalog snapshot; re-run scripts/sync-providers.js after harness upgrades.
  DeepSeek can be checked on demand with the "verify pricing" button.
• DeepSeek historical pricing only covers audited windows: policies carry
  [since, until]; unaudited gaps and retired aliases (deepseek-chat/deepseek-reasoner)
  are marked unpriced instead of inheriting old prices forever.
• Official daily spend uses the Beijing day boundary (Asia/Shanghai), independent of
  the host/server timezone.
• The model series tag is a display heuristic: brand-new model names may show no
  tag or a generic one; it never affects pricing.
• Balance freshness has latency: DeepSeek balances refresh at most every 10s (other
  providers 60s), and the provider's own balance settlement may lag further.

Structure

dsh-billing-glass/
├── README.md
├── package.json              # dsh.bundle + dsh.client(web) declaration
├── cordis.patch.yml          # composition patch layer
├── scripts/
│   ├── build-client.js       # src/client/* → lib/client.js (install still needs no build)
│   └── sync-providers.js     # pi-ai catalog sync + provenance recording
├── src/client/               # maintainable browser source (component/format/model-badge/materials)
└── lib/
    ├── index.js              # host: aggregate route /api/billing-glass/state + event pricing
    ├── ledger.js             # append-only JSONL spend ledger
    ├── client.js             # build artifact (edit src/client, then run the build)
    └── providers/
        ├── registry.js       # provider abstraction & registry (extension point)
        ├── deepseek.js       # DeepSeek provider (balance/daily spend/pricing)
        ├── deepseek-pricing.js # DeepSeek official price engine (policy chain + peak/valley)
        └── catalog.generated.js # pi-ai snapshot + PI_AI_CATALOG_META provenance

Installation

From GitHub (recommended):

dsh plugin --profile web add github:linkingoscar/dsh-billing-glass

Local checkout (development):

dsh plugin --profile web add link:$(pwd)

Then restart dsh web and refresh the page. Requires a harness with the dsh plugin
command and a DEEPSEEK_API_KEY configured in Settings → Models (the balance query
reuses that key; nothing leaves your machine).

Security / trust boundary

• The plugin performs no caller authentication; it assumes the harness webServer is
  localhost-bound or sits behind host-provided auth middleware. If the host exposes the
  web server publicly, add authentication at the host layer.
• GET /api/billing-glass/state and GET /api/billing-glass/ledger are read-only
  (balance/today external fetches are TTL-cached, so UI polling cannot amplify them).
• Side-effecting routes are POST: /api/billing-glass/refresh-balance (force-refresh
  a provider balance) and /api/billing-glass/refresh-pricing (fetch the official price
  page and possibly write a snapshot).
• The DeepSeek platform token is only used host-side against the platform's internal
  usage endpoint, and today-consumed results are cached for 5 minutes.

Adding an API provider

Built-in scope matches the harness official provider list exactly (no setup):

• The registry ships 27 providers (lib/providers/catalog.generated.js), generated
  by scripts/sync-providers.js from the harness's built-in pi-ai official catalog —
  names, baseURLs and per-model official prices (USD/1M) all match the provider list in
  the harness model settings. Whichever provider is chosen in Settings → Models or used
  by a session, the overlay switches automatically.
• DeepSeek uses a dedicated provider (exact peak/valley policy-chain pricing);
  Moonshot / OpenRouter additionally have public balance-endpoint adapters; other
  providers price session cost as usual and show "no public balance endpoint" for the
  balance.
• After a harness upgrade, re-run node scripts/sync-providers.js to sync the catalog
  and prices.
• Catalog provenance is auditable: catalog.generated.js exports
  PI_AI_CATALOG_META (source / sourceVersion / sourceSha256 / generatedAt), written
  automatically by the sync script and enforced non-null by CI.

Custom providers outside the official list (graceful degradation + guided loop):

When a session uses a provider missing from the harness official catalog (baseURL
mismatch), the overlay shows a ⚠ guidance strip:

Unrecognized provider "xxx": not in the harness official provider list. Tell the
assistant its pricing scheme (unit prices/subscription) or its official price page in
chat, and the assistant will wire it up.

Once the user gives a pricing scheme in chat, the generic factory
defineOpenAiCompatProvider (lib/providers/openai-compat.js) onboards it in one shot —
permanent and automatic from then on.

1. Create lib/providers/<vendor>.js implementing the provider contract (see the
   comment at the top of registry.js):

   export const myVendor = {
    id: "my-vendor",
    displayName: "My Vendor",
    currency: "USD",
    aliases: ["my-vendor-official"],   // harness provider-id aliases (names seen in header/config)
    defaultModel: "my-model",
    keyRef: "MY_VENDOR_API_KEY",       // credential ref (used to detect a configured key)
    plan: { kind: "token", label: "Pay-as-you-go · official prices" },
    // subscription providers:
    // plan: { kind: "subscription", label: "Pro plan", fee: 20, currency: "USD", period: "month" },
    async fetchBalance(ctx) { /* returns { total, granted, toppedUp, available, currency } */ },
    // must return null when the model is unknown and no `*` fallback exists (fail closed)
    priceAt(model, timeMs) { /* returns { cny, usd, mode } unit price, or null */ },
    // costNative is the provider-native amount; costUsd is the aggregation base
    costOf(usage, unit) { /* returns { costNative, nativeCurrency, costUsd, ...tokens } */ },
    async todayConsumed(ctx, config, balance) { /* optional, returns number | null */ }
   };

2. Register it in the PROVIDERS array in registry.js (order = display order;
   DeepSeek stays first).

3. Pick the provider/model in harness Settings → Models, or make one request through it
   — the overlay switches to show its name, plan and fee system automatically.

4. Restart dsh web — the UI and the aggregate route gain a section with no further
   changes.

Provider-switch signals (auto-detected)

Provider ids are normalized through aliases (e.g. the harness DeepSeek provider id is
deepseek-official); the pi-ai gateway matches by baseURL hostname (baseUrlHosts,
e.g. api.moonshot.cn → Moonshot Kimi); unknown baseURLs are never mis-assigned.

Verification

npm ci                               # locked devDependency (pi-ai catalog sync)
npm test                             # unit + render smoke + state-route integration
npm run check:generated              # rebuild client bundle + rerun catalog sync, then git-diff verify
npm run pack:check                   # release package contents check
dsh --profile web --dump-config        # composition tree check (the bundle row appears)
# on-device: restart dsh web; the glass capsule appears in the bottom-right corner

CI (.github/workflows/ci.yml) runs the same gates on every push/PR.

License

Apache-2.0 © 2026 linkingoscar

The pricing engine was ported from
bpc-oss/dsh-web-billing (MIT license);
its copyright notice is retained in
THIRD_PARTY_NOTICES.md as required by the MIT terms.