DSH plugin token metering: measurements and pressure
"The context is nearly full" has three different meanings in DSH plugin: pressure already incurred, the cost of the next request, and the surface's route-priced total. They come from different fields, and mixing them produces the classic mismatch — the meter shows headroom while the request gets compacted. Read the snapshot correctly before arguing about thresholds.
A measurement is a snapshot, not a running total
TokenMeasurement is a detached immutable snapshot at one log revision.(source)
It is not a counter that grows by itself. logRevision is the number of persisted events consumed to produce every field, equal to the next unread event sequence. The snapshot is immutable and does not advance as replay folding moves — for fresh numbers, call measure() again.
That design matters to plugins: you can safely attach a measurement to a message, cache it, or pass it across async boundaries without fear of silent mutation. Conversely, do not cache one long-term as "current pressure," because it describes only the moment it was produced.
What the six fields each answer
Each field answers a different question; mixing them yields wrong conclusions.(source)
| Field | What it answers |
|---|---|
logRevision | How many persisted events this snapshot is based on |
baseline | Which anchor this measurement used |
surfaceDeltaTokens | Signed repricing of surface content relative to the anchor |
totalTokens | Current non-negative request and response pressure |
surfaceTokens | The surface's route-priced total |
nodes | Current surface nodes, in position order |
surfaceDeltaTokens is the only field allowed to go negative: it preserves growth and shrinkage relative to a matching anchor, priced under the same route on both sides. surfaceTokens equals the sum of all node prices, which is the most useful fact when debugging "why do these two numbers disagree" — add the node prices first.
nodes follows surface order, not seq order. Surface order is authoritative: a replacement node's persisted seq can be higher than nodes positioned after it, so never sort by seq before pricing.
baseline is the anchor, estimated is the fallback
Reuse provider usage when you can, re-estimate the whole envelope when you cannot.(source)
Every measurement resolves the effective envelope's route provider/model through ctx.llm into that route's declared request image pricing. Images are therefore priced as the vision tokens the request actually sends plus model-visible text; routes and combinations without declared pricing keep fixed heuristics.
baseline.kind === 'usage' requires two conditions at once: the most recent successful provider call used the same canonical request envelope, and that call's total was not below its full route pricing anchor. The second condition is conservative — a smaller usage must never be used to suppress current pressure.
estimated means no reusable conservative usage anchor exists and the service prices the full envelope and surface itself. Later successful requests replace earlier anchors. That replacement explains a behavior people find odd: totalTokens jumps after a few requests because the anchor changed, not because content suddenly grew.
TokenSurfaceNode: request price and shadow price
A node carries two prices: the route-priced request cost and a route-independent heuristic.(source)
TokenSurfaceNode has exactly three fields: seq, tokens, and heuristicTokens.
tokens is the request pressure of the exact message this node projects under the measured route: images use declared vision pricing when the route adapter declares it, otherwise a fixed heuristic. Triggering, retention, and range selection all read this price.
heuristicTokens is the same message's fixed heuristic token count, independent of any route. It exists for the shadow-price protocol: replacements are priced with this value so the O(1) projection fold stays consistent with its own append. In other words, tokens serves "what this request costs" while heuristicTokens serves "how folding stays self-consistent."
That also means you cannot budget with heuristicTokens, nor compare across routes with tokens. The former ignores routes; the latter is bound to one.
ContextPressureProjection: for display, not gating
Its three fields are last values from different moments, not one atomic observation.(source)
ctx.tokenMeter.contextPressure(session) synchronously reads the latest recorded pressureTokens and contextWindow; the client projection also derives projectedTokens from surface changes.
pressureTokens— the last request's provider prompt size: uncached input plus cache reads and writes, excluding output, so it does not grow while the current turn streams; absent until the provider reports usage.projectedTokens— the next request's prompt cost:pressureTokensplus a heuristic re-estimate of surface changes since that sample. It estimates increments only, so it stays anchored to the provider while reacting immediately when compaction masks a range — somethingpressureTokenscannot do, because compaction reports no usage.contextWindow— the latest recorded route capacity, absent when no adapter declares one.
The reference is explicit: these fields are not one atomic request observation, and switching models can pair new capacity with the previous route's pressure until the next request reports usage. That trade-off is intentional — this is a user-facing reference, not billing or gating input.
A status bar can use it. A hard gate cannot. To answer "will the next request blow up," call measure() yourself.
measure and contextPressure are not interchangeable
Display values do not price a new request; request pricing is measure() only.(source)
measure(session, requestHeader?) meters current request pressure and surface through a persisted-tail replay. requestHeader replaces the most recent envelope for pressure and node pricing, but the node set always describes the current session surface. Each call clones those positional nodes, so cost is O(surface).
Two usage rules follow: poll status frequently with contextPressure(), which reads recorded values only; and call measure() before sending a request or making a compaction decision, since only it recomputes under the new envelope. For a single-message estimate, use estimateMessage(message), which returns content and role-framing tokens under fixed service heuristics.
One easily missed boundary: the measure() anchor includes every surface node before the assistant message, including input admitted after step/start. Inject content right before a request and it counts toward pressure.
Verification: near the ceiling and after compaction
Verification must align on three points: display value, request pricing, and post-compaction change.(source)
- Build a session with no reported usage and assert
contextPressure()has nopressureTokenswhilemeasure()still returns a usable measurement. - Let one request report usage and assert
pressureTokensappears withbaseline.kind === 'usage'. - Append several long messages and assert
projectedTokensrises whilepressureTokensstays put. - Trigger compaction and assert
projectedTokensdrops immediately whilepressureTokensremains at the old sample. - Sum node prices and assert the result equals
surfaceTokens, confirming surface order rather than seq order. - Switch to a route with declared image pricing and call
measure()again, assertingtokenschanges for the same image node whileheuristicTokensdoes not.
If step 4 shows no drop, first confirm compaction actually masked a surface range — projectedTokens sees increments only and never predicts replacements that have not happened.
For the output side of compaction, see compaction results and pruning; for reference budget truncation, see session reference budget.
One line to close: a measurement is immutable, the six fields answer six questions, tokens follows the route while heuristicTokens follows folding, display values never gate, and only measure() prices a request.
FAQ
No. DSH plugin measurements are detached immutable snapshots. DSH plugin records the persisted event count each field consumed as logRevision, so the snapshot never grows as replay folding advances.
No. DSH plugin defines them separately: totalTokens is non-negative request and response pressure, while surfaceTokens is the surface's route-priced total equal to the sum of node prices.
Not advisable. DSH plugin calls it a user-facing reference. Its three fields are last values from different moments, so a model switch can pair new capacity with old route pressure.
Because DSH plugin estimates increments only: the last request's pressure plus a heuristic re-estimate of surface deltas. Masking a surface range shows up immediately, which pressureTokens alone cannot do.
Related Terms
- TokenMeasurement
- TokenMeasurement is a detached immutable snapshot of request pressure and surface at one consumed log revision, with six read-only fields.— packages/llm/token-meter/src/types.ts
- logRevision
- logRevision is the count of persisted events consumed to produce every field in the measurement, equal to the next unread event sequence.— packages/llm/token-meter/src/types.ts
- TokenSurfaceNode
- TokenSurfaceNode is one priced node of the current ordered surface: event seq, request-pressure tokens, and route-independent heuristicTokens.— packages/llm/token-meter/src/types.ts
- ContextPressureProjection
- ContextPressureProjection is the display-oriented pressure approximation with pressureTokens, projectedTokens, and contextWindow.— packages/llm/token-meter/src/projection.ts
Sources
- DeepSeek Harness reference - Token metering· deepseek-ai
- packages/llm/token-meter/src/types.ts· deepseek-ai