dsh-token-breakdown-stats
English | 中文
A dsh plugin (dsh-plugin
topic) that replaces the composer-dock statistics pill so a session's token
total covers the main agent plus every subagent it called, with a
click-open breakdown by billing bucket, by subagent, and by model.
Summary
The composer-dock statistics pill in a dsh session reports only the main
agent's token usage. When that agent delegates to subagents, every token the
subagents spend is invisible in the session footer.
This plugin replaces that pill so the footer reports the session total —
main agent plus every subagent it called — and its click-open dialog
itemizes the usage by billing bucket, by subagent, and by model.
What changes
| shipped pill | this plugin |
|---|
| Pill label | main-agent total + cache hit | session total (main + subagents) + cache hit + subagent count |
| Dialog | four billing buckets | buckets, main/subagent split, subagent aggregate, per-model rows |
| Time/activity pill | turns, steps, speed, timings | unchanged (reproduced) |
Subagents are reported as an aggregate everywhere: the pill shows how many
there were, and the dialog folds them into one block (count, how many are still
running, share of the session, and the summed buckets). No per-subagent rows —
a session can spawn dozens, and the per-child detail already lives in the
subagent catalog in the session header.
The dialog shows:
- 总用量 — the four disjoint billing buckets (uncached input, cache read,
cache write, output) plus cache hit, over the whole session tree.
- 主 Agent — the provider/model routes observed in the loaded turns, and
that session's own buckets.
- 子 Agent（N） — one aggregate block: how many were discovered, how many
are still running, their share of the session total, and the folded buckets.
- 按模型 — per provider/model totals folded from the loaded turns.
- A friendly note when the session has not called any subagent yet.
How it works
The plugin registers the same dock cell the shipped ui-chat row uses —
conversation.composer.dock, id stats, order 0 — so it replaces the
built-in pill rather than adding a second one. A list slot rejects a second
registration that reuses an id at the same priority, so this row passes
priority: -1, strictly below the shipped row's 0 (lowest renders).
Every figure rides durable projections, so paging and compaction cannot change
them:
tokenUsage — the four disjoint provider billing buckets per session.subagentCatalog — direct children of a session, in parent event order,
with mode and optional label.SessionSummary.projectionValues — the same projections plus the subagent
identity (label) and timing, addressed by session id.ChatSnapshot.nodes.values() — the keyed store of every materialized Chat
Node. turn-tail rows deliberately make no contribution to legacy.nodes,
so this is the only place the per-turn routes (provider/model) can be read
from; the legacy slice still feeds the step-count fold.
The compact / detailed preference is read from the same ui-chat config
scope the shipped pill uses; compact keeps the plain speed and cache-hit
readings without dialogs.
Known limitations
- Per-subagent model attribution is unavailable. The client-side
tokenUsage projection carries only the four buckets — no route — so a
subagent's row shows its total, not its model. Model attribution covers the
main session's loaded turns.
- Descendants are a best-effort walk.
subagentCatalog is the direct
children of a session; grandchildren appear only once their own catalog has
been loaded (the same rule the shipped subagent catalog follows). Nothing is
invented for unloaded levels.
- Model attribution covers loaded turns.
turn-tail rows exist only for
closed turns inside the loaded window, so on a long, paged session the model
row and the by-model section can lag the durable totals. In this version the
chat target's assistant nodes carry no providerMetadata, so there is no
second source to fall back on — the row shows the session's models only once
at least one closed turn is loaded.
- Compact mode keeps the shipped behavior (speed and cache hit only).
Install
The bundle is a plain directory — no build step is required, because
client.js is committed. Install it into a profile from a local clone:
git clone https://github.com/Minggle/dsh-token-breakdown-stats.git
Then, in a dsh session, install the bundle with plugin_manager:
plugin_manager action: install_bundle
target: <absolute path to the cloned directory>
The inserted row id is token-breakdown-stats. Restart the app (or let the
live patch reload apply it) and the pill in the composer dock is replaced.
To rebuild client.js from src/ after editing the sources:
node build.mjs
Verify
node src/smoke.test.cjs
The smoke test loads the built client.js through a mocked
window.__ModuleLoader__ and a minimal React runtime, then asserts the
rollup math, the pill label, the dialog sections, Escape dismissal, compact
mode, and locale parity.
Files
index.js — Host half (no Host row is needed).client.js — generated browser artifact (do not edit).src/entry.js — slot registration and mode hook.src/stats-pills.js — the two pills and the breakdown dialog.src/token-aggregator.cjs — pure aggregation and route folding.src/smoke.test.cjs — Node smoke test.locale/{en,zh}.json — dictionaries (single source of truth).icon.svg — original artwork.build.mjs — inlines src/ into client.js.
Requirements
- DeepSeek Harness
>= 0.2.0-rc.2 (the plugin reads ChatSnapshot.nodes,
SessionSummary.projectionValues, and the conversation.composer.dock
slot's list-cell priority rule).
- A desktop or web profile; the Web GUI renders the pill.
Install incident (2026-10-15)
An early build of this plugin made the desktop app fail web boot with
1 entry did not activate: @deepseek-ai/dsh-client-ui-chat: failed. The
bundle was removed and the profile restored from the backup the app itself
wrote (cordis.patch.yml.bak-*), so no user data was lost.
The root causes are recorded here because both are easy to reintroduce:
- A list slot rejects a same-id, same-priority registration. The shipped
ui-chat row occupies conversation.composer.dock id stats at priority
0; a replacement must pass a strictly lower priority (this plugin uses
-1). The slot's register throws
already has an entry with id "stats" at priority 0 … register at a different priority to shadow it (lowest renders), and because the plugin's
inject callback runs inside the dock owner's fiber, the failure is reported
against that owner rather than the plugin.
- A restricted Client context throws on an undeclared service. Reading
ctx.configForms without declaring configForms in the entry's inject
raises cannot get property "configForms" without inject. The plugin now
declares only ['slots', 'locale'] and reads everything else defensively.
Two smoke-test mocks reproduce both failure modes so a regression fails the
test instead of a boot: the context throws on undeclared service access, and
the slot service rejects a duplicate cell at the same priority.
License
MIT
