English · 简体中文

dsh-provider-usage

Every provider's balance, one glance away. A DeepSeek Harness plugin that floats a small draggable usage ball over the Web GUI — no more logging into each provider console to check whether you are about to run out of credit mid-session.

Features

• Auto-detection — enumerates the provider routes registered in the current profile (ctx.llm); zero configuration for well-known routes.
• Per-kind wire adapters — routes with no public balance/usage API (Google, Mistral, Groq, Bedrock, Azure, Qwen Token Plan, …) are listed as unsupported instead of being silently dropped:

Screenshots

The floating ball (bottom-left, with the green healthy halo) and the open usage panel:

OpenAI Codex via OAuth

OpenAI Codex is a ChatGPT-subscription provider: it authenticates with an OAuth access token, not an API key, so there is nothing to paste into a key field. dsh itself has no OAuth button for this route — but this plugin can still query its usage, because it reads the OAuth grant out of the harness credential store. Set the provider up once, and the usage panel shows your real 5-hour / weekly Codex windows.

1. Make sure the route exists

The sign-in writes a grant record addressed llm-pi-ai/openai-codex, and the route has to be configured for ctx.llm to list it. With the stock llm-pi-ai adapter mounted (default in the web profile), an empty profile is enough — e.g. in ~/.dsh/settings.yaml:

llm-pi-ai:
providers:
openai-codex: {}

2. Sign in through the harness authorization seam

dsh-llm-pi-ai registers an "OpenAI (ChatGPT Plus/Pro)" OAuth flow for openai-codex on the harness authorization seam (ctx.authorization, credential key llm-pi-ai/openai-codex). Complete it from any surface that runs that flow — a sign-in entry on the harness model/authorization UI, or any pi-ai client whose login persists through the harness credential store. Finish the browser (or device-code) flow with your ChatGPT account. The harness then stores the grant under ~/.dsh/.credentials.yaml as llm-pi-ai/openai-codex:

records:
llm-pi-ai/openai-codex:
kind: grant
payload:
type: oauth
access:
refresh:
expires:
accountId:

> The grant must land in the harness credential store (the record above). Codex clients that keep their own credential file (e.g. dsh-codex's $DSH_HOME/.openai-codex-auth.json, or the Codex CLI's ~/.codex/auth.json) do not write this record, so this plugin cannot see them.

3. Watch the usage

That's it. The route is auto-detected (ctx.llm lists openai-codex), and the plugin:

1. reads the grant record from the credential store on every poll (no caching),
2. refreshes the OAuth token automatically when it is within 30 s of expiry, deciding and rotating inside the store's exclusive lock — so a concurrent process that already rotated the grant is adopted instead of spending the same single-use refresh token twice, and a write that fails is reported rather than swallowed,
3. calls GET https://chatgpt.com/backend-api/wham/usage with Authorization: Bearer and the ChatGPT-Account-Id header derived from the token's own JWT claim, retrying once after a refresh if the endpoint answers 401.

The panel then shows your subscription's 5h limit, weekly windows (used %, reset countdown) plus credits and spend control balances when the plan reports them. If the grant is missing the card reads "OAuth authorization missing (llm-pi-ai/openai-codex)" — sign in again with step 2. If upstream instead rejects the stored refresh token (refresh_token_reused / invalid_grant, i.e. the token was already spent or revoked and the rotation never landed here), the card reads "OAuth authorization expired — sign in to Codex again" with the raw upstream detail on hover, and the plugin stops calling the token endpoint for ten minutes instead of once per poll.

4. Troubleshooting: intermittent "Our servers are currently overloaded"

The Codex backend occasionally answers with Codex error: Our servers are currently overloaded. Please try again later., and the harness fails the round with PI_AI_ERROR. This is transient overload on OpenAI's side (account, quota, and network are usually fine — GET /wham/usage confirms window headroom), yet the default configuration never retries, for two reasons:

1. pi-ai's Codex client recognizes overloaded as retryable, but its default retry count is 0 (dsh-llm-pi-ai explicitly passes maxRetries: 0);
2. once the error bubbles up, its text contains no 5xx / rate limit / timeout keyword, so it is classified as the catch-all PI_AI_ERROR — which is not among dsh-llm-retry's default retryable codes (EMPTY_RESPONSE / RATE_LIMIT / SERVER / TIMEOUT / TRANSPORT), so the round fails immediately.

Add a retryPolicy for this provider in ~/.dsh/settings.yaml that includes PI_AI_ERROR in the retryable codes (takes effect on a new session):

llm-pi-ai:
providers:
openai-codex:
retryPolicy:
mode: normal
maxRetries: 10
retryableCodes:
- EMPTY_RESPONSE
- RATE_LIMIT
- SERVER
- TIMEOUT
- TRANSPORT
- PI_AI_ERROR
backoff:
initialDelayMs: 2000   # first retry delay, doubled each attempt
maxDelayMs: 60000      # per-attempt delay cap
jitterRatio: 0.2       # ±20% jitter

Do not confuse this with the other, deterministic failure: some models are unavailable to ChatGPT-subscription accounts, and the backend answers 400 The '' model is not supported when using Codex with a ChatGPT account. (observed with e.g. gpt-5.3-codex-spark, gpt-5-codex). That is a permanent error — retrying won't help; switch to a model your account supports (e.g. the gpt-5.4 / gpt-5.5 / gpt-5.6 families).

Volcengine Ark Agent Plan / Coding Plan

Volcengine Ark's subscription plans (Agent Plan / Coding Plan) do not expose their quota on the inference endpoint. It lives on Volcengine's control plane (OpenTOP OpenAPI) and has to be signed with an IAM AK/SK pair (V4 HMAC-SHA256). The plan key on the route (ARK_AGENT_PLAN_API_KEY, …) is a data-plane key that only authorizes model calls — quoting it for usage is refused upstream (observed: GetAFPUsage requires Volcengine Ark SSO STS), so those routes need the AK/SK pair in addition to the inference key.

1. The route

The baseURL picks the adapter: a path containing /api/plan is an Agent Plan, /api/coding a Coding Plan.

llm-pi-ai:
providers:
ark-agent-plan:
displayName: Volcengine Ark - Agent Plan
apiKeyEnv: ARK_AGENT_PLAN_API_KEY
api: openai-responses
baseURL: https://ark.cn-beijing.volces.com/api/plan/v3
ark-coding-plan:
displayName: Volcengine Ark - Coding Plan
apiKeyEnv: ARK_CODING_PLAN_API_KEY
baseURL: https://ark.cn-beijing.volces.com/api/coding   # Anthropic wire; use /api/coding/v3 for the OpenAI-compatible endpoint

The route id is arbitrary; the well-known ids ark-agent-plan, ark-coding-plan, ark-agent-plan-cn and ark-coding-plan-cn are recognized even when the profile omits baseURL.

2. Configure the AK/SK pair

Create or read an Access Key ID / Secret Access Key in the Volcengine console under Access Control (IAM) → Access keys (read access is enough for quota), then supply it either way:

# ~/.dsh/.credentials.yaml (a process environment variable or a project .env of the same name works too)
refs:
VOLC_ARK_ACCESS_KEY_ID: AKLT...
VOLC_ARK_ACCESS_KEY_SECRET: ...

Each half takes the first ref that resolves: VOLC_ARK_ACCESS_KEY_ID → VOLC_ACCESS_KEY_ID → VOLC_ACCESSKEY, and VOLC_ARK_ACCESS_KEY_SECRET → VOLC_ACCESS_KEY_SECRET → VOLC_SECRETKEY → VOLC_SECRET_KEY.

Until the pair is configured the card reads "missing key (VOLC_ARK_ACCESS_KEY_ID + VOLC_ARK_ACCESS_KEY_SECRET)"; a wrong pair surfaces the control-plane error verbatim (e.g. HTTP 401: InvalidAccessKey: The security token[...] is invalid.).

3. What it shows

• Agent Plan — the 5h, weekly and monthly windows, with the used percentage derived from the absolute Used/Quota pair and a reset countdown (AFPDaily is omitted, matching the Ark console and arkcli).
• Coding Plan — the session (5h), weekly and monthly windows, using the backend's own used percentage. A plan that is unsubscribed or reclaimed reports no rows.

Install

> [!NOTE]
> Requires an existing DeepSeek Harness installation.

npm

dsh plugin --profile web add dsh-provider-usage@latest

Build from source

git clone https://github.com/lizhouai/dsh-provider-usage.git
cd dsh-provider-usage
pnpm install
pnpm build
pnpm pack   # produces dsh-provider-usage-.tgz
dsh plugin --profile web add ./dsh-provider-usage-.tgz

Install the tarball, not the repo directory: dsh plugin --profile web add . links the repo, whose own node_modules then shadows the harness's shared @deepseek-ai/cordis instance and the host half never registers (RPC 404). The link form is still handy for client-only UI iteration — the browser bundle is self-contained, so a rebuild + page refresh picks it up — but switch to the tarball (or the npm release) whenever you need the host half. If pnpm fails with EPERM ... symlink while replacing a linked install, delete the stale node_modules/dsh-provider-usage junction in the profile directory and retry.

Restart dsh web after changing the plugin set (a plugin add/remove requires a restart; afterwards, code changes only need a rebuild + re-add + page refresh).

Upgrade

dsh plugin --profile web add dsh-provider-usage@latest

Then restart dsh web and refresh the page. If the release you want was published very recently, your profile's supply-chain cooldown (minimumReleaseAge) may silently keep the older version — pin the exact version instead (dsh plugin --profile web add dsh-provider-usage@0.3.10) and dsh will exempt it automatically. The version badge in the panel header confirms which release is actually loaded.

Host compatibility

The host packages this plugin imports (@deepseek-ai/dsh-credentials, -settings, -typert-protocol, -launch-environment) are not installed from npm: a profile resolves them through $DSH_HOME/profiles/node_modules into the running dsh's own single copy. dsh's peer gate compares those declared ranges against the runtime version, so a narrow range such as ^0.1.2-alpha.3 makes every dsh minor release skip the plugin with skipping profile bundle.

This plugin therefore declares an open lower bound — >=0.1.2-alpha.3 — which the gate accepts for any runtime, prereleases included. The field itself stays: a peer name is also what makes dsh's loader bind that import to the harness's copy instead of to whatever the profile's node_modules happens to hold.

Two consequences worth knowing:

• A dsh release that renames a seam this plugin reads is not blocked; it degrades instead, and provider-usage: this dsh provides no … in the harness log names what is missing (src/host-seams.ts). The compat workflow replays the gate and drives a live usage/list against the latest and next release lines daily, so drift surfaces in CI rather than in your panel.
• npm install is stricter than the gate: standard semver never matches a prerelease (0.2.0-rc.1) against an open range, so npm answers ERESOLVE. Install through dsh — dsh plugin --profile web add … uses pnpm, which is what the harness itself installs plugins with.

Configuration

Defaults work out of the box: the plugin auto-detects every provider route of the active profile. A trusted profile can tune behavior in ~/.dsh/profiles/web/cordis.patch.yml — override the bundle's row by id (the package's own bundle patch already inserts it; a second insert of the same id fails the boot with duplicate loader entry id):

- id: provider-usage
name: dsh-provider-usage
config:
refreshSeconds: 60          # suggested panel refresh interval (5–86400)
balanceRedThreshold: 10     # balance below this turns red (per the balance's own currency)
balanceYellowThreshold: 30  # balance below this turns yellow (per the balance's own currency)
autoDetect: true            # enumerate provider routes from the llm registry
queryTimeoutMs: 20000       # per-attempt query timeout; each retry gets a fresh timeout
queryRetries: 2             # retries for transient errors (timeout/network/HTTP 408/425/429/5xx)
queryRetryDelayMs: 2000     # base retry delay, doubled per attempt, capped at 10s
providers: []               # manual specs; an id matching a detected route overrides it

The same fields can be hot-updated under the provider-usage: namespace in ~/.dsh/settings.yaml.

Adding a manual provider

config:
providers:
- id: my-deepseek-gateway
kind: deepseek
baseURL: https://my-gateway.example.com
apiKeyEnv: MY_GATEWAY_KEY
displayName: My Gateway

How it works

• Host half (src/index.ts): UsageService extends TypertRemoteService exposes usage/list via the Remote('list') marker, applied without decorator syntax (SRC mode, no codegen). Config is declared with schemastery, and the settings provider's installSection enables hot updates from the settings document.
• Client half (src/client/): a window.__ModuleLoader__.load({id, factory}) bundle (built by tsdown) mounts through the sidebar.footer.action slot (used purely as a mount point — the trigger itself is a floating ball portaled to document.body) and polls usage/list through ctx.connection.rpc.call('/api', 'usage/list', {args:{}}) on its own interval. The service stays stateless — every poll fetches live values.

License

MIT