dsh-balance-pill

dsh-balance-pill

DeepSeek Harness web plugin: a small, always-visible DeepSeek balance pill (e.g. CNY 42.17). With a chat session open it sits in the session header; without one it pins to the top-right corner of the app, so it is always on screen. No dashboard, charts, or settings UI.

Screenshots

Balance pill visible with and without a chat session (green = off-peak):

Peak-hours settings under Settings → Plugins → Plugin configuration:

Layout

dsh-balance-pill/
  package.json       dual-face metadata (dsh.bundle + dsh.client), zero deps, no scripts
  cordis.patch.yml   bundle layer: inserts the Host row into the profile
  lib/index.js       Host half: credentials resolve + Node fetch + webserver route
  lib/client.js      Browser half: the pill in the header + shell.overlay fallback
  docs/              README screenshots

How it works

• The Host half is a Cordis plugin row inserted by this package's cordis.patch.yml bundle layer. It injects the existing credentials and webServer services and registers one exact route, /dsh-balance-pill, on the web server.
• Per request the Host resolves DEEPSEEK_API_KEY through credentials.resolve(...), calls GET https://api.deepseek.com/user/balance with Node's built-in fetch (Authorization: Bearer), and returns the minimum payload the UI needs: { "ok": true, "balance": 42.17, "currency": "CNY" } or { "ok": false }.
• The browser half registers the BalancePill React component (id balance-pill) into two seats, as thin views over one shared balance store. Inside a chat session it contributes to the conversation.session.header.utilities seat, so it rides the session header's flex row without ever covering the header's own controls. It also contributes to the frame-wide shell.overlay seat — an always-visible, additive layer — pinned to the top-right corner, but renders there only while the header is not showing its own pill (no session open in the main view, or a still-blank one), so the pill is always on screen without duplicating or overlapping. The shared store owns the single poll of the same-origin route — first fetch on the first mounted view, then every 60 seconds, plus on click — so the API is polled once per minute no matter which seat is mounted, and seat switches never trigger extra requests. Loaded state shows CNY 42.17; loading shows …; any failure shows a muted – — one neutral error state, no details.
• The Host half also registers one settings namespace, dsh-balance-pill (settings.register) holding the peak-hours config. The browser half edits that namespace through a card on the Settings → Plugins → Plugin configuration page and reads it to tint the pill; the settings service persists it to the profile's settings document (~/.dsh/settings.yaml), so the config survives reloads without editing or rebuilding the bundle.

Peak-hours coloring

The pill shades the whole button by whether the user's current local time is inside a configured peak-hours window:

• Peak hours → a subtle red tint.
• Off-peak → a subtle green tint.

The window is configurable from the UI, no rebuild needed: open Settings → Plugins → Plugin configuration, expand Balance pill peak hours, set the timezone and the ranges (one HH:MM - HH:MM per line), and Save. The config persists to ~/.dsh/settings.yaml (namespace dsh-balance-pill) and the pill retints on the next check. The shape the UI edits is:

{
  timezone: "UTC",
  peakHours: [
    ["01:00", "04:00"],
    ["06:00", "10:00"],
  ],
}

• The ranges are evaluated in timezone, then compared against the user's current local time (the local timezone is read from the browser via Intl.DateTimeFormat().resolvedOptions().timeZone).
• A range is inclusive of its start and exclusive of its end. A range whose end is at or before its start wraps across midnight to the next day, so ["23:00", "01:00"] spans that whole window.
• DST transitions are handled (boundaries are resolved via Intl twice).
• The check runs on mount, every 60 seconds, and whenever the persisted config changes, so the tint stays current. It is independent of the balance fetch: the color reflects the peak status even while the balance is loading or unavailable.
• Invalid ranges are rejected by the card's validation; an empty peakHours list is always off-peak.

Security posture

• The API key exists only in the Host process, in a local variable scoped to the single fetch, used solely for the Authorization header. It is never logged, persisted, serialized, or sent to the browser.
• The browser only ever receives { ok, balance, currency } or { ok: false }.
• The plugin reads no files directly (.credentials.yaml is owned by the credentials service) and spawns no processes.
• The only external network destination is https://api.deepseek.com/user/balance.

Install

Requires a DeepSeek Harness web profile and a configured DEEPSEEK_API_KEY (via the harness credentials service).

dsh plugin --profile web add github:ivbrajkovic/dsh-balance-pill

Then restart the web profile and reload the GUI. The bundle patch inserts the Host row automatically; the browser half is picked up via dsh.client.

Pin a commit if you want a fixed revision:

dsh plugin --profile web add github:ivbrajkovic/dsh-balance-pill#<commit>

Local development

From a checkout of this repo:

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

After edits, restart the web profile and reload the page. If the profile still has a manual balance-pill row in its own cordis.patch.yml, remove that row so the bundle layer is the only mount (avoids double-loading).

Verify

1. Start or restart the web profile (dsh web / pnpm dlx @deepseek-ai/dsh web).
2. Open http://localhost:3080 — the pill is always visible: pinned to the top-right corner while no session is open (e.g. CNY 42.17, or – if the key is missing), and inside the session header once a chat session is open, without covering any header controls.
3. Open Settings → Plugins → Plugin configuration, expand Balance pill peak hours, set timezone and ranges, Save — the pill retints on the next check (within 60s).