Overview

@lovstudio/dsh-account-balance

DeepSeek Harness global account-balance card: live session/job status plus GLM / KIMI quota windows and OpenRouter / DeepSeek balances, pinned to the shell overlay bottom-right

README / EN

Package documentation

@lovstudio/dsh-account-balance

English | 中文

A persistent bottom-right status card for the DeepSeek Harness web surface. It pins into the root shell.overlay seat and shows, across the whole process:

a status dot plus 「空闲 / N 会话 · M 任务」 (idle, or live session and running background-job counts), polled every 3 seconds;
GLM / KIMI rows with two 5px quota bars — the 5-hour window and the weekly allowance — colored green (<50%), orange (≥50%) or red (≥80%) with a hover tooltip showing usage, remaining, and the reset countdown;
OpenRouter (US$) and DeepSeek (¥) remaining balances, polled every 60 seconds through a 55-second Host cache.

The Host half exposes two Typert Remote faces — accountBalance.status and accountBalance.quotas. status is a pure in-memory snapshot over ctx.agents.list() and ctx.jobs.list(); it never scans session logs, so the 3-second browser poll stays sub-millisecond and cannot stall a user message. quotas fans the four provider requests out in parallel and caches the result for 55 seconds; every external number is normalized at the wire boundary and rows are shaped strictly by mode, so the Remote JSON never carries an undefined field. Provider credentials resolve per operation through ctx.credentials (ZAI_CODING_CN_API_KEY, KIMI_CODING_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY) and never leave the Host.

Install

Prerequisites: Node.js 22.19+ or 24+, pnpm 11 (corepack enable or npm i -g pnpm) — dsh plugin forwards to pnpm inside the profile directory.

From a DeepSeek Harness source checkout (recommended — you get the harness source too):

git clone --depth 1 --branch dsh-v0.1.2-rc.1 https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && pnpm install && pnpm run build
pnpm dsh plugin --profile web add -w github:lovstudio/dsh-account-balance#v0.1.3
pnpm dsh web

Without a checkout (npx; compiled harness only):

npx @deepseek-ai/dsh plugin --profile web add -w github:lovstudio/dsh-account-balance#v0.1.3
npx @deepseek-ai/dsh web

web is the profile dsh web boots. The tag pins a commit whose lib/ is prebuilt and committed, so nothing is compiled on your machine. Verified on 2026-09-04 against dsh-v0.1.2-rc.1 in both forms. Remove with dsh plugin --profile web remove @lovstudio/dsh-account-balance.

Service API

`accountBalance.status(): Promise<RemoteResult<AccountBalanceStatusSnapshot>>`

Live process status: { sessions, tasks } — distinct live session ids and background jobs currently in the running state.

`accountBalance.quotas(): Promise<RemoteResult<AccountBalanceQuotaSnapshot>>`

Four-provider snapshot: { at, rows: { glm, kimi, or, ds } }. Window rows (glm, kimi) carry mode: 'windows' with windows.w5 and windows.week; balance rows (or, ds) carry mode: 'balance' with balance and detail. Every row carries a status of ok | no-key | no-data | error.

Config

No configuration. The four provider credentials are read from the credential service by reference; a missing key renders the row as 「—」 with a tooltip reason.

Local development

Install dependencies and keep the Host and Client artifacts current from this repository:

pnpm install
pnpm run watch

Mount the checkout into an isolated development profile rather than editing the DeepSeek Harness workspace or the default ~/.dsh profile:

DSH_HOME=/Users/mark/.dsh-lov-dev pnpm --dir /path/to/deepseek-harness dsh plugin --profile web add -w link:/path/to/dsh-account-balance

Extension points

None — the card is a leaf surface. Consumers may read the same two Remote faces for their own status/quota displays.

Model Experience

What the model sees

Nothing. The card is browser-only UI; both Remote calls run outside model turns and their results never enter a prompt.

Token effect

Zero — the plugin performs no model calls.

KV Cache effect

None — no prompt prefix is contributed.

Known Limitations and Deferred Work

jobs.list() visibility — the Host status handler lists jobs without a caller, so jobs owned by another session may not be counted as tasks; unowned and visible jobs are counted.
Quota shape drift — GLM and KIMI wire formats are extracted defensively; an API shape change surfaces as no-data rows rather than a crash.
Page reload / restart — the plugin is a composition row, so it survives both once installed; before install it behaves like any other plugin package in this workspace.

LIMITATIONS

Known limitations

- **`jobs.list()` visibility** — the Host status handler lists jobs without a caller, so jobs owned by another session may not be counted as `tasks`; unowned and visible jobs are counted. - **Quota shape drift** — GLM and KIMI wire formats are extracted defensively; an API shape change surfaces as `no-data` rows rather than a crash. - **Page reload / restart** — the plugin is a composition row, so it survives both once installed; before install it behaves like any other plugin package in this workspace.

@lovstudio/dsh-account-balance