dsh-context-governor

English | Русский | 中文

A DeepSeek Harness plugin: a session context indicator — prompt size, step cost,
cache-hit, bands and the compaction threshold, DeepSeek balance and the
peak/off-peak tariff, plus a handoff button.

It never calls a model and spends no tokens at all — details below.

What it looks like

The chip in the session header opens the panel below. The same panel is available
in English, Chinese and Russian:

English	中文	Русский

The handoff button sits next to the model selector:

No tokens, no model calls

Everything the plugin shows is measurement and arithmetic. It reads tokens and
the window from harness projections, computes the cost with the configured rates
and fetches the balance over HTTP.

• No generation requests. Not for review, not for summarization, not in the
  background: the plugin never asks a model to compute anything.
• Zero tokens. The plugin sends no provider requests and spends none of your
  budget. Its only touch of the LLM layer is reading the model catalog
  (resolveModelInfo) for the window and limits; that is not generation and not
  billable tokens.
• Nothing is modified. It does not touch the history, the system prompt or the
  prefix cache, so it cannot affect prompt caching.
• The network is used for the balance only. The harness account service (when
  signed in) and api.deepseek.com/user/balance are not a model. Plus git status
  on a handoff click, locally.

Install

As a package:

dsh plugin --profile web add dsh-context-governor

From source:

dsh plugin --profile web add github:mpinaev/dsh-context-governor

Locally, without installing: drop the directory into
~/.dsh/profiles/web/plugins/ and reference the file from the profile's
cordis.patch.yml:

- insert:
    - id: context-governor
      name: /absolute/path/to/dsh-context-governor/index.js

Installed as a package, the host half is read at startup, so restart dsh web
and reload the page — the client half is served as a revision snapshot.

Check it with npm test: the smoke test runs the host half against a stub
harness, with no network and no model calls, and pins the compaction threshold,
the cache buckets, the step cost and the balance provider gate.

Supported DSH versions

DSH version	State
0.1.7-rc.2 … <0.2.0	supported, verified live
0.2.0-rc.1 … <0.3.0	range declared; probed weekly by CI

DSH disables the plugin when its declared range does not cover the running
version (peer ranges are matched with prereleases included). That is why the host
logs its token source and tariff at startup: if those lines are missing, the plugin
is probably disabled, and dsh --dump-config will say so.

Development

git clone https://github.com/mpinaev/dsh-context-governor.git
cd dsh-context-governor
npm test                     # 58 assertions: no network, no model calls
./scripts/compat-check.sh    # boots a spare instance on 3099 and asks its API
dsh plugin --profile web add "link:$PWD"

Rules and the release flow live in CONTRIBUTING.md.

What it shows

• prompt size (uncached input + cache tokens) and an estimated step cost in USD
  (DeepSeek only; for other providers no price is shown at all);
• a cost multiplier relative to base (fresh input = 1.0, cache read =
  cacheReadRate/freshRate, about 0.02 for deepseek-flash);
• cache-hit over the session totals, % (a partial hit is never rounded up to 100);
• cold input per step (fresh tokens in the last request);
• a band: 0 = normal, 1 = warn, 2 = high, 3 = critical;
• DeepSeek balance (numbers only; the key never reaches the client);
• peak/off-peak tariff with a countdown to the switch.

Why a multiplier over the raw prompt lies. For deepseek-flash a cache read is
50 times cheaper than fresh input ($0.003 versus $0.15 per 1M off-peak). At 99%
cache-hit a 260k context costs about $0.0015 per step, while prompt/base would
report x2.6. That is why the cost is computed per bucket: fresh x freshRate,
cache read x cacheReadRate, cache write x cacheWriteRate, output x
outputRate.

Data sources

Tokens. Prompt size, cache-hit and output come from the harness projection
tokenUsage (service ctx.sessionProjections): uncachedInputTokens,
cacheReadTokens, cacheWriteTokens, outputTokens. These are the
provider's authoritative numbers: they survive paging and compaction and close the
slot correctly on a retry (llm/retry-started), so a repeated attempt does not
double count. Without projections in the build, the plugin falls back to its own
fold of llm/stream.

Cache-hit is computed from the session totals, not from the last step alone, so
it agrees with the harness cache-hit pill. A partial hit is never rounded up to
100 — extra decimals are added instead, and only a miss-free hit shows exactly
100%.

Window and threshold. The model window and pressure come from the
contextPressure projection (contextWindow, pressureTokens); the output
reserve comes from request/header (the request maxTokens). The compaction
threshold is computed exactly as the harness does (dsh-compaction-basic):

threshold = min(thresholdRatio * window, window - reserve - headroom)

The threshold belongs to its own session. Window and reserve are kept per
session: a session whose route is not known yet reports a window unknown instead
of another model's threshold. No bands are invented while the window is unknown.

Three input buckets, each with its own rate. A cache read (default $0.003/1M)
is 50 times cheaper than fresh input, while a cache write on DeepSeek is billed as
ordinary input (cacheWriteRate, default = freshRate). Cache-hit is the
share of the prompt served from cache on read; a cache write does not count as
a hit. A provider that has no prompt cache at all declares cached: false in its
providerRates entry: the cache rows, the cache rates and the cache-hit marker
disappear, and the cacheHitLow and cold-prefill warnings stay quiet. Without the
flag they would hang on every step — a cacheless provider reads 0% cache-hit and
sends the whole prompt as fresh input by definition.

Money. Neither DSH nor the provider reports token cost in dollars anywhere, so
the plugin keeps its own rates table (off by default for providers it does not
know). The chip/balance logic is therefore:

• the price is shown only where the plugin has rates for the provider — by
  default DeepSeek (deepseek-official, ids starting with deepseek), plus any
  provider declared in providerRates or listed in pricedProviders. For any
  other provider (cline, clinebot, OpenRouter, pi-ai, …) nothing price-related is
  computed or displayed: the chip drops the cost segment, and the panel drops the
  step-cost, relative-to-base and rates rows — no invented dollar figure and no
  "price unavailable" placeholder either;
• rates are per provider: providerRates.<id> overrides the default
  freshRate / cacheReadRate / cacheWriteRate / outputRate, so a second
  provider can carry its own numbers (and its own peakMultiplier);
• the peak/off-peak tariff (⚡/🌙, the ×N multiplier, Chinese holidays) is
  DeepSeek's, so it is shown only for a seasonal provider: by default an id
  starting with deepseek. A foreign provider has a flat rate; declare
  seasonal: true in its providerRates entry if it really follows DeepSeek's
  schedule. A flat provider gets neither the time marker nor the tariff rows.

Signals

• a server log entry when a session enters a band, on a cold prefill and on an
  expensive step;
• a client chip in the session header, coloured by band, with a details panel;
• on the chip: the balance and, for a provider that follows DeepSeek's schedule,
  the tariff marker (peak / off-peak with countdown).

Peak/off-peak tariff and balance

Tariff. The DeepSeek rule is fixed: peak is Beijing time (UTC+8), on weekdays,
09:00–12:00 and 14:00–18:00; everything else, weekends included, is off-peak and
costs half. The local timezone plays no part in the decision, only in the display.
The configured rates (freshRate, cacheReadRate, cacheWriteRate, outputRate) are
off-peak; at peak they are multiplied by peakMultiplier (2 by default), so the
step cost and the warnings follow the tariff of the moment. The countdown runs to
the next real switch: boundaries inside a weekend are skipped, so after Friday
18:00 it counts to Monday 09:00, not to Saturday. On a provider with that
schedule, at peak the tariff marker, the Beijing time and the balance are drawn in
red, in both the chip and the panel, so the expensive hours are visible at a
glance.

Chinese public holidays. The official rule has an easy-to-miss caveat: peak is
weekdays excluding Chinese public holidays, and on those holidays DeepSeek
stays off-peak around the clock. The plugin takes the year's calendar from a
maintained source (holidayUrl, by default the data of the chinese-days
package), caches it on disk once (holidayCacheDir, default
<DSH_HOME>/cache/context-governor) and refreshes itself — no code to edit every
year. The network is used in the background only: if the calendar has not arrived,
the tariff falls back to the weekday rule and the panel honestly says the holiday
calendar is not loaded. Your own dates can be set with the holidays config — an
array of 'YYYY-MM-DD' or 'YYYY-MM-DD..YYYY-MM-DD' ranges; they apply
immediately, take priority over the source and work without a network. On a
holiday the tariff row reads "off-peak (Chinese holiday)" and the countdown skips
the whole holiday to the next working peak. The network can be turned off
entirely: holidayFetch: false.

Balance. Sources in order:

1. The official platform account — the harness service ctx.deepseekAccount
   (getBalance). It works when the account is signed in and the client has sent
   its build version; wallets arrive as strings, the currency may be CNY or USD,
   and bonus wallets come as a separate list.
2. The API key — GET https://api.deepseek.com/user/balance, with the key
   from the credentials seam (DEEPSEEK_API_KEY) or from the environment.

The source field says where the numbers came from: account or api-key.
The fallback to the second source is deliberate: another build may have no platform
sign-in, and the balance must not disappear because of that.

The balance is shown only for DeepSeek providers. On cline, clinebot and any
other provider a foreign total on the chip is plain misinformation: no balance is
displayed there, and the panel shows a DeepSeek-only note instead of a number. The
provider list is configurable through balanceProviders (default
['deepseek-official']), and any id starting with deepseek is accepted. If a
session has no route of its own yet, the provider is not guessed and the balance
stays hidden.

The key never leaves the host: only numbers reach the client (total, bonus,
top-up, currency, availability). Concurrent reads collapse, and failures degrade
into a state (no-credential, error, disabled) rather than an exception. The
refresh button clears the cache and re-reads the balance and the tariff.

The currency is not converted. The step cost and the configured rates
(freshRate, cacheReadRate, cacheWriteRate, outputRate — all $/1M) are in
US dollars, while the balance is printed in whatever currency the source reports
(USD or CNY for DeepSeek), to the cent. The plugin never converts between them, so
a ¥ balance and a $ step cost in the same chip are different units — compare
them only after converting yourself.

Route access. /context-governor/api/* are closed by a guard header and an
Origin check: a request must carry x-dsh-context-governor: 1 (only the plugin
client sets it) and must not be cross-origin. Without the header — 403, with a
foreign Origin — 403. A plain loopback GET without Origin is allowed, which
keeps curl diagnostics convenient.

The practical point: at 99% cache-hit an expensive step is not a large context but
fresh input or a cache miss, and the tariff doubles that difference.

Handoff button

One click: the host assembles a session summary (task, state, cwd, touched files,
child sessions), the client opens a new session in the same workspace through
ctx.uiWorkspace.startSession() and puts the summary into its draft. There are
no branches or fallbacks: no Alt+click, no insertion into the current session, no
clipboard.

Two declared services keep it reliable:

• the client declares inject = ['slots', 'uiWorkspace']: without the declaration
  Cordis does not hand over the service, and the button used to slip into the
  fallback paths instead of opening a session;
• the host declares inject = [... 'sessionQuery']: without it the summary came
  out with no task, state or paths (placeholders only).

The summary reaches the new session lazily: the click remembers the text,
startSession() opens the session, its input slot renders, and the same
component puts the text into the draft through inputActions.setDraft.

UI languages

Languages: en (default), zh, ru. The switch is a small button next to
the refresh control in the chip header: it shows the current code (EN / Chinese /
RU) and cycles the language. The choice is remembered in the browser
(localStorage: dsh-context-governor.lang) and immediately re-renders both the
chip and the handoff button.

The language covers all interface text (panel labels, warnings, tooltips) and the
language of the document the handoff button inserts into the new session: the
client passes lang to /api/handoff. The host returns data without text
(band, tariff and warnings are codes), so switching the language needs no data
refetch.

Thresholds

The plugin never hardcodes the model window — it reads it from the harness:

1. The main source is the contextPressure projection (contextWindow,
   pressureTokens) of ctx.sessionProjections: the authoritative window of
   the live session.
2. The output reserve is the request maxTokens from the request/header
   event; until then request/context (contextWindow) serves as a hint.
3. The model catalog (ctx.llm.resolveModelInfo for
   agentDefaultModel.currentSelection()) remains a hint until the first request.

Window and reserve are kept per session.

The compaction threshold and the bands are derived from the window:

reserve               = request maxTokens
compaction threshold  = min(thresholdRatio * window, window - reserve - headroomTokens)
band i                = bandRatios[i] * compaction threshold

With a 1,000,000 window and a 256,000 reserve the threshold is 678,464 and the
bands are 237k / 407k / 577k. With an 800,000 window the threshold is 478,464 and
the bands 167k / 287k / 407k. The formula matches dsh-compaction-basic
(window - reserve - headroom); with constant bands, critical would sit below the
real prefix-rewrite threshold.

The plugin adapts to different models in different sessions: every session keeps
its own route window, and another session's window is never substituted. If the
window has not been resolved yet, the bands are not invented (there are none) and
the panel shows a model-window-unknown warning.

In the context-governor block of ~/.dsh/profiles/web/cordis.patch.yml you
can tune only bandRatios, headroomTokens, thresholdRatio, the default rates
(freshRate, cacheReadRate, cacheWriteRate, outputRate,
peakMultiplier), the per-provider overrides (pricedProviders,
providerRates — rates, seasonal, cached, peakMultiplier) and the signal thresholds
(anomalyDelta, anomalyCostUsd, cacheHitFloorPct); for the holiday calendar —
holidays, holidayFetch, holidayUrl, holidayCacheDir, holidayRetryMs,
holidayTimeoutMs; for the balance — balanceEnabled,
useAccountBalance, balanceProviders, balanceTtlMs,
balanceTimeoutMs. windowTokens and reservedTokens can be forced, but
they default to 0, meaning ask the harness; hardcoding them loses the
adaptivity.

Notes

The bands are derived from the model window; the warn/high/critical labels are not
read back. The plugin measures and never trims: it does not change history or the
prompt.

License

MIT — see LICENSE.