dsh-flash-ctx-mon
The context monitor companion plugin for the core
dsh-flash package — it registers its own alert
provider and its own panel switch instead of living inside the core's apply().
Apache-2.0
中文
What it does
Two capabilities, one in each half of the plugin:
- Context monitor — reads the precise token usage DSH already reports on its
session event stream and turns pressure on the model's context window into
dsh-flash alerts, at three rising thresholds.
- Session skills chip — a chip beside the conversation tabs listing the skills the
current session has actually loaded, resolved against the skill catalog.
The monitor is on by default — only an explicit "off" turns it off — and it is
entirely client-side.
What it registers
Host half — src/index.ts → dist/index.js
A Cordis plugin named dsh-flash-ctx-mon.
| Thing | Detail |
|---|
| Settings namespace | dsh-flash-ctx-mon |
| Fields | ctxApproxWindow, ctxThresholdInfo, ctxThresholdWarning, ctxThresholdError, ctxPollBase, ctxPollMin, modelContextWindows, modelContextWindowSources |
| Routes | none |
| Host-side services | none (inject: []) |
The host half exists only to hold the settings namespace and its schema. There is no
collector and no route, because there is nothing to collect on the host: token usage
arrives through DSH session events (ctx.get('sessions')), the model catalog through
remote.session.modelCatalog(), and the skill catalog through remote.skills.list() —
all of it in the browser.
Browser half — src-client/ → lib/client.js (esbuild bundle)
| Registration | Through |
|---|
Alert provider dsh-flash-ctx-mon:context-alert | ctx.get('dockFlashAlerts').registerProvider() |
Panel switch dsh-flash-ctx-mon:monitor-context | ctx.get('quickControl').registerSwitch() |
Session skills chip dsh-flash-ctx-mon-skills | ctx.inject(['slots']) → conversation.session.header.actions, rendered onto the session's tab strip |
Switch properties: type: 'toggle', group: 'system', cluster: 'system-alerts',
order: 59, icon: 'message', plus a Configure button. Its visibility follows
dsh-flash's dock-flash:system-alerts master toggle — with the alert registry switched
off there is nothing for this switch to drive. It deliberately carries no subtitle:
the live "model · 12%" readout it used to print on the row is already the first thing in
the panel the Configure button opens.
Dual discovery, plus a fallback poll. ctx.get('quickControl') /
ctx.get('dockFlashAlerts') resolve asynchronously, so registration has three routes:
the dock-flash:ready event (dsh-flash loaded after us), a synchronous ctx.get()
check (it loaded before us), and a fallback poll of up to 15 attempts 200 ms apart.
The first to succeed sets _registered, so nothing registers twice.
The switch
In dsh-flash's quick panel, under ⚙️ System → System Alerts, find Context
Monitor:
- turning it off writes
'0' to localStorage['dsh-flash-ctx-mon:monitor-context']
and calls setProviderEnabled(…, false) on the alert registry, so the provider stops
producing alerts;
- turning it on restores both.
Who wins. The browser key is the authority, and absence means on
(getItem(key) !== '0'). The host's own fields are all volatile(), so DSH resets them
to their defaults on every restart — the browser is what remembers your choice.
The config modal
Configure beside the switch opens the context monitor panel:
| Control | Range | Step | Default |
|---|
Context Window Size ctxApproxWindow | 64000–512000 tokens | 8000 | 128000 |
Info Threshold ctxThresholdInfo | 30–80 % | 1 | 70 |
Warning Threshold ctxThresholdWarning | 50–92 % | 1 | 85 |
Error Threshold ctxThresholdError | 70–98 % | 1 | 95 |
Context Poll Base Interval ctxPollBase | 5000–60000 ms | 1000 | 20000 |
Context Poll Min Interval ctxPollMin | 1000–10000 ms | 500 | 2000 |
Below the sliders the panel reports the live state — Current Model, Window Size,
Window Source (Session Event / Model Catalog / Error Parsed / Manual / Built-in /
Fuzzy Match / Fallback), Data Source (Precise / Awaiting data), Input Tokens and
Context Pressure — and carries the Model Window Map editor, a Refresh
Catalog action, and a preview of what the alert messages look like.
Alerts
Emitted only when the token source is precise; with no session-event usage data the
monitor reports "Awaiting data" and emits nothing — it does not guess from message
counts.
| Level | At | Title |
|---|
| ℹ️ info | ≥ ctxThresholdInfo (70 %) | Session context getting long |
| 🟡 warning | ≥ ctxThresholdWarning (85 %) | Session context nearly exhausted |
| 🔴 error | ≥ ctxThresholdError (95 %) | Session context almost exhausted |
Each message carries the percentage and the reading it came from — model · 12.4K/128K in precise mode. Alerts are dismissible and flow through dsh-flash's
registry, so they appear in the panel's alert list and as toasts like any other.
How a model's window is resolved
_resolveWindow(model) reads modelContextWindows — the user-mapped table in the
settings namespace — and labels each answer with its provenance from
modelContextWindowSources. A model that is not in the map resolves to null, and the
caller falls back to ctxApproxWindow (the "Fallback" source).
The built-in window table has been retired. _KNOWN_WINDOWS is empty and the
catalog auto-fill is a documented no-op, so today the map is the only source of a real
window size — which is why the panel's Model Window Map editor is how you teach it about
a model it gets wrong.
Both map fields are volatile(), and that is not a statement that they are
transient. The settings service rejects any patched path that is not under a volatile
node (Config field "…" is not volatile), so a non-volatile modelContextWindows
meant every mapping the panel wrote was rejected, rolled back and lost — a mapped
model kept falling back to ctxApproxWindow. Volatile is what makes the write legal;
the value still lands in the profile patch and survives a restart.
Polling
The monitor samples on an adaptive interval: ctxPollBase is the ceiling used while
usage is low, and the interval tightens as usage rises, never below ctxPollMin. In
precise mode the base interval is doubled automatically, because the event source pushes
updates rather than being polled. A skill being used forces an immediate poll, so its
notice is claimed while the use is still fresh.
The skills chip
The chip is drawn on the session's tab strip, directly after the last conversation tab.
DSH puts no session id on that strip — data-conversation-session marks the conversation
body only — so the header chip is what keeps it per-session: it stays registered into
conversation.session.header.actions as dsh-flash-ctx-mon-skills (order 15), renders a
hidden anchor carrying the id the slot handed it, walks up from that anchor to the nearest
ancestor holding exactly one strip, and mounts the visible chip there. An ancestor holding
more than one strip means another session is involved, so the chip stays in the header; a
session with a single conversation view has no strip at all, and the header chip remains
where it always was. A MutationObserver re-places the chip when a strip is rebuilt or
another tab appears.
It lists the skills the current session has loaded — subagents and other sessions are
excluded, because the slot hands the component the id of the session it renders for.
Detection uses DSH's own marker: the <skill_content name="X"> block emitted when a
skill body is loaded. It arrives on two paths — the model calling the skill tool, and a
user typing /name in the composer (which produces no tool call of its own) — and a
failed call carries no block, so failures are not counted. Names are resolved against the
skill catalog (remote.skills.list()), and the popup shows uses, first/last use and the
catalog description, with Open in sidebar.
The tracker is deliberately independent of the monitor switch: the chip keeps working
with the context monitor switched off.
Settings
| Field | Default | Notes |
|---|
ctxApproxWindow | 128000 | Fallback window for a model the map does not know |
ctxThresholdInfo | 70 | % of the window |
ctxThresholdWarning | 85 | % — must exceed the info threshold |
ctxThresholdError | 95 | % — must exceed the warning threshold |
ctxPollBase | 20000 | ms, the low-usage ceiling |
ctxPollMin | 2000 | ms, the floor |
modelContextWindows | {} | model id → window size |
modelContextWindowSources | {} | model id → provenance tag |
Dependencies
| Package | Type | Purpose |
|---|
@deepseek-ai/cordis | peer | the plugin framework |
dsh-flash >=1.0.0-0 <2.0.0-0 | peer | supplies the quickControl and dockFlashAlerts services and the dock-flash:ready event |
dock-base >=0.1.2-0 <1.0.0-0 || >=0.2.0-0 <1.0.0-0 | peer, optional | workbench mode only |
@deepseek-ai/schemastery | dependency | the settings schema (volatile()) |
There is no hard dependency on the core dsh-flash: every service is resolved through
ctx.get(...), and compatibility is declared by the peer range — the same shape the
dock-flash v3 adapter uses towards dock-base. The range >=1.0.0-0 <2.0.0-0 covers the 1.x
line, prereleases included.
Install
dsh plugin --profile <profile> add dsh-flash-ctx-mon
Requires dsh-flash ≥ 1.0 — it supplies the quickControl and
dockFlashAlerts services and the dock-flash:ready event, and the 1.x line satisfies it.
Restart DSH after installing.
cordis.patch.yml inserts the host row. Its name is a package name, resolved
through the profile's node_modules — never a relative path.
The browser half needs no row: the module loader discovers it from package.json's
exports["./client"] plus dsh.client and serves it at
/plugins/dsh-flash-ctx-mon/client.js.
Build
pnpm install
pnpm run build # tsc → dist/index.js + esbuild → lib/client.js
pnpm test # Vitest unit tests for src-client pure logic
pnpm run typecheck
node scripts/verify-config-volatile.mjs ./dist/index.js
dist/index.js is tracked on purpose, for the same reason dsh-flash tracks its own:
a git install fetches sources and runs no build script, so a repository without dist/
would arrive missing the host entry point that main and exports["."] point at.
lib/client.js is also tracked on purpose (the browser half ships pre-built): the module
loader requires a single-file window.__ModuleLoader__.load(...) bundle, and the loader's
require resolves react/react-dom at runtime, so those are kept external. Its source
lives under src-client/ and is bundled with esbuild:
pnpm run build:client # src-client/index.js → lib/client.js
build:client is folded into pnpm run build. The pure logic (tokens, skill-detect) is
split into src-client/*.js modules that are unit-tested with Vitest (pnpm test) and
genuinely shared with the bundle; the stateful browser-half logic (prefs, token source,
skill tracker, provider, i18n) intentionally stays inline in factory-body.js because it is
coupled to that closure's private session-event state.
scripts/verify-config-volatile.mjs loads the built host half and re-runs the settings
service's own volatile-path test against it — the invariant the two map fields must
satisfy, or every write to them is rejected.
Layout
src/index.ts HOST half → tsc → dist/index.js
src-client/index.js BROWSER source entry → esbuild → lib/client.js
src-client/*.js pure logic modules (tokens, skill-detect) — unit-tested
lib/client.js compiled browser half — tracked on purpose
dist/index.js compiled host half — tracked on purpose
test/ Vitest unit tests for the pure logic modules
cordis.patch.yml bundle layer: inserts the host row into the profile
scripts/ build-client.mjs — the panel's esbuild bundle step
scripts/ verify-config-volatile.mjs — the volatile-schema check
.github/workflows/sync-from-gitee.yml — the Gitee → GitHub mirror
Gitee is the authoritative repository; GitHub (github.com/tcgbp/dsh-flash-ctx-mon) is a
mirror of it and the host of the release tarball.
Privacy and limits (deliberate)
- Nothing leaves the machine. The monitor reads DSH's own session events and two
client remotes; it has no host route, no collector and no outbound request.
- Precise or nothing. With no session-event usage data the monitor shows "Awaiting
data" and raises no alert, rather than estimating from message counts.
- Per-session skills only. The chip counts the current session; subagent sessions and
other conversations are excluded. A session that is no longer retained reports "Skill
catalog unavailable" with a Retry.
- Bounded tracking. Tracked skills are capped at 200 per session (defensive), and a
skill notice is only announced for a use within the last 15 seconds, so replaying a
session's history does not fire a burst of notices.
- UI language: the panel and the alert text carry both Chinese and English, and
follow DSH's language setting.
