dsh-token-total 1.0.0 → 1.0.2

package/lib/types/client/ContextUsageEntry.d.ts

@@ -0,0 +1,22 @@
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots';
+import { type ContextBreakdownLike, type ContextPressureLike } from './context-meter-core.ts';
+export declare const CONTEXT_LOCALE_NS = "tokenTotalContext";
+declare const keys: readonly ["label", "used", "system", "tools", "messages", "aria", "thousand", "million"];
+export type ContextLocaleKey = typeof keys[number];
+export declare const CONTEXT_LOCALES: Record<string, Record<ContextLocaleKey, string>>;
+type ProjectionMap = {
+    contextPressure: ContextPressureLike;
+    contextBreakdown: ContextBreakdownLike;
+};
+type UseContextProjection = <K extends keyof ProjectionMap & string>(key: K) => ProjectionMap[K] | undefined;
+export interface ContextUsageEntryProps extends PropsLocale<typeof CONTEXT_LOCALE_NS> {
+    useProjection: UseContextProjection;
+    installContextTakeover?: (anchor: HTMLElement) => () => void;
+}
+export declare function ContextUsageEntry({ useProjection, t, installContextTakeover }: ContextUsageEntryProps): JSX.Element | null;
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        tokenTotalContext: ContextLocaleKey;
+    }
+}
+export {};

package/lib/types/client/context-meter-core.d.ts

@@ -0,0 +1,26 @@
+export interface ContextPressureLike {
+    projectedTokens?: number;
+    pressureTokens?: number;
+    contextWindow?: number;
+}
+export interface ContextBreakdownLike {
+    systemTokens: number;
+    toolsTokens: number;
+    messageTokens: number;
+}
+export interface ContextOccupancy {
+    percent: number;
+    usedTokens: number;
+    contextWindow: number;
+}
+/** Mirrors the host meter's occupancy calculation exactly. */
+export declare function contextOccupancy(pressure: ContextPressureLike | undefined): ContextOccupancy | null;
+export declare function contextBreakdownTotal(breakdown: ContextBreakdownLike | undefined): number;
+export declare function contextBreakdownSegments(percent: number, breakdown: ContextBreakdownLike | undefined): Array<{
+    key: string;
+    width: number;
+}>;
+export declare function formatContextTokens(value: number, units: {
+    thousand: string;
+    million: string;
+}): string;

package/lib/types/client/context-takeover.d.ts

@@ -0,0 +1,4 @@
+/** The host ContextMeter is hard-coded beside composer.dock, not a slot.
+ * Suppress only that recognizable sibling while our replacement is mounted;
+ * never hide a whole dock, slot wrapper, or another plugin's readout. */
+export declare function installContextTakeover(anchor: HTMLElement): () => void;

package/lib/types/client/locales.d.ts

@@ -7,7 +7,7 @@
 /** The locale namespace this plugin owns. */
 export declare const LOCALE_NS = "tokenTotal";
 /** The typed translator key union for the panel's locale seat. */
-export type TokenTotalKey = 'nav' | 'back' | 'range' | 'rangePreset.today' | 'rangePreset.3' | 'rangePreset.7' | 'rangePreset.30' | 'rangePreset.90' | 'rangeCustom' | 'from' | 'to' | 'refresh' | 'loading' | 'tokens' | 'tokensHint' | 'tokensUnit' | 'inputTokens' | 'outputTokens' | 'cacheTokens' | 'cachedTokens' | 'sessions' | 'requests' | 'activeDays' | 'cacheRate' | 'cacheRateHint' | 'cacheHitRate' | 'hitRateLegend' | 'topModel' | 'topModelHint' | 'heatmap' | 'heatLess' | 'heatMore' | 'dailyTrend' | 'hourlyTrend' | 'trendLimited' | 'usageRanking' | 'byModel' | 'byProvider' | 'tokensColumn' | 'cacheRateColumn' | 'providerModels' | 'other' | 'total' | 'percent' | 'asOf' | 'empty' | 'stats.counts' | 'stats.tokensPerSecond' | 'stats.cacheHit' | 'stats.cacheMiss' | 'stats.dialog.title' | 'stats.dialog.usageTitle' | 'stats.dialog.llmTime' | 'stats.dialog.toolTime' | 'stats.dialog.ttft' | 'stats.dialog.speed' | 'stats.dialog.main' | 'stats.dialog.subagents' | 'stats.dialog.subagentCount' | 'stats.dialog.treeTotal' | 'message.turnUsage.count' | 'message.turnUsage.cacheHit' | 'message.turnUsage.input' | 'message.turnUsage.cacheRead' | 'message.turnUsage.cacheWrite' | 'message.turnUsage.output';
+export type TokenTotalKey = 'nav' | 'back' | 'range' | 'rangePreset.today' | 'rangePreset.3' | 'rangePreset.7' | 'rangePreset.30' | 'rangePreset.90' | 'rangeCustom' | 'from' | 'to' | 'refresh' | 'loading' | 'tokens' | 'tokensHint' | 'tokensUnit' | 'inputTokens' | 'outputTokens' | 'cacheTokens' | 'cachedTokens' | 'sessions' | 'requests' | 'requestsFailed' | 'activeDays' | 'cacheRate' | 'cacheRateHint' | 'cacheHitRate' | 'hitRateLegend' | 'topModel' | 'topModelHint' | 'heatmap' | 'heatLess' | 'heatMore' | 'dailyTrend' | 'hourlyTrend' | 'trendLimited' | 'usageRanking' | 'byModel' | 'byProvider' | 'tokensColumn' | 'cacheRateColumn' | 'providerModels' | 'other' | 'total' | 'percent' | 'asOf' | 'empty' | 'stats.counts' | 'stats.tokensPerSecond' | 'stats.cacheHit' | 'stats.cacheMiss' | 'stats.dialog.title' | 'stats.dialog.usageTitle' | 'stats.dialog.llmTime' | 'stats.dialog.toolTime' | 'stats.dialog.ttft' | 'stats.dialog.speed' | 'stats.dialog.main' | 'stats.dialog.subagents' | 'stats.dialog.subagentCount' | 'stats.dialog.treeTotal' | 'message.turnUsage.count' | 'message.turnUsage.cacheHit' | 'message.turnUsage.input' | 'message.turnUsage.cacheRead' | 'message.turnUsage.cacheWrite' | 'message.turnUsage.output';
 export declare const en: Record<TokenTotalKey, string>;
 export declare const zh: Record<TokenTotalKey, string>;
 export declare const zhTW: Record<TokenTotalKey, string>;

package/lib/types/client/session-usage-core.d.ts

@@ -0,0 +1,9 @@
+/** Pure billing helpers shared by the session-tree hook and composer pills. */
+import type { SessionUsageTotals, SessionUsageTree } from '../wire.ts';
+/** Add the root and descendants once; tree.total is already that sum. */
+export declare function combinedTotals(tree: SessionUsageTree, self?: SessionUsageTotals): SessionUsageTotals;
+/** One consistent split for the pill, cache hit rate and every dialog row. */
+export declare function sessionUsageForDisplay(native: SessionUsageTotals | undefined, tree: SessionUsageTree | null): SessionUsageTree;
+export declare function hasAnyTokens(totals: SessionUsageTotals | undefined): boolean;
+export declare function billedTotal(totals: SessionUsageTotals): number;
+export declare function cacheHitPercentOf(totals: SessionUsageTotals): number | null;

package/lib/types/client/use-session-usage.d.ts

@@ -1,24 +1,8 @@
 import type { SessionUsageTotals, SessionUsageTree } from '../wire.ts';
-/** Fold a tree into the flat shape the pill's dialog renders. */
-export declare function combinedTotals(tree: SessionUsageTree): SessionUsageTotals;
-/** Whether a totals record carries any billable token at all. */
-export declare function hasAnyTokens(totals: SessionUsageTotals | undefined): boolean;
-/** Total billed tokens of a flat totals record (prompt side + completion). */
-export declare function billedTotal(totals: SessionUsageTotals): number;
-/** Cache hit rate over the prompt side, or null when nothing was prompted. */
-export declare function cacheHitPercentOf(totals: SessionUsageTotals): number | null;
+export { billedTotal, cacheHitPercentOf, combinedTotals, hasAnyTokens } from './session-usage-core.ts';
 export interface SessionTreeReading {
     tree: SessionUsageTree | null;
-    /** main + subagents, or null before the first successful answer. */
+    /** Authoritative log-based main + all descendant usage after the tree loads. */
     totals: SessionUsageTotals | null;
 }
-/**
- * Subscribe to one session's whole-tree usage.
- *
- * `signature` is any string that changes when the native usage figure moves;
- * passing it in keeps this hook out of the projection seat and lets the caller
- * decide what "a new call settled" means for its own pill. A session that turns
- * out to have subagents additionally re-asks on a slow beat, because subagent
- * spend lands in a different session log and no native figure moves for it.
- */
 export declare function useSessionUsage(sessionId: string | undefined, signature: string): SessionTreeReading;

package/lib/types/collector.d.ts

@@ -3,10 +3,10 @@
  * Two sources feed the same fold:
  *
  * - live: `session/event` subscription — every committed session event
- *   reaches this plugin after the fact. `assistant/message` carries the
- *   step's final `usage` (TokenUsage); `assistant/chunk` carries an early
- *   `usage` sample from the streaming adapter; `request/context` carries the
- *   provider/model route. A completed call's usage is attributed to the model
+ *   reaches this plugin after the fact. Assistant messages expose final usage,
+ *   and modern message/attempt streams retain raw usage even on failed calls.
+ *   Legacy `assistant/chunk` reports an early sample; `request/context` carries
+ *   the provider/model route. A completed call's usage is attributed to the model
  *   the request used — in priority order: the message's own `source`
  *   (authoritative per call), then the session's last-known route, which
  *   comes from observed `request/context` events OR is lazily seeded from
@@ -27,11 +27,10 @@
  *   >= 0.1.2-rc.1, 0 for a non-forked session), and the replay skips it —
  *   the parent's own backfill already counted those events.
  *
- * Idempotence: within ONE session, the same (turn, step) may report usage
- * more than once (a streaming sample then the final assistant/message;
- * compaction replays). The fold emits each (turn, step) key exactly once and
- * keeps the newest values in its own state — see the replaceSample note for
- * why the store observably keeps the FIRST emission. Cross-session
+ * Idempotence: within ONE session, repeated reports for the same (turn, step)
+ * emit only signed bucket corrections: the accumulated usage is last-wins.
+ * A started retry closes that replacement slot because its predecessor was a
+ * separately billed attempt. Cross-session
  * (turn, step) collisions are NOT deduped: two sessions both own a turn 1 /
  * step 1, and each must count. The store's per-day rows accumulate, so
  * re-folding the same log must not add twice: live events are only folded
@@ -75,6 +74,17 @@ export declare class UsageFold {
      *  carries no (new) usage or turn marker. */
     fold(ev: UsageSessionEvent): UsageSample | null;
     private replaceSample;
+    /**
+     * Fold one `assistant/attempt` — a provider call that failed. Tokens follow
+     * the same last-report-wins rule as a committed message (the attempt's
+     * stream is the call's final word, so a usage chunk seen mid-stream is
+     * replaced or corrected, never added twice), but the call must ALWAYS be
+     * counted as one failure: `replaceSample` drops an all-zero first report,
+     * which is correct for the token buckets and would silently lose the
+     * failure. A failed call that reported no usage therefore contributes a
+     * zero-token failure marker instead of a null.
+     */
+    private attemptSample;
     /**
      * Fold one `compaction/summary` — the one place a provider call's usage
      * reaches the log OUTSIDE the agent loop. The summarization call produces no
@@ -201,8 +211,13 @@ export declare class UsageCollector {
      *  untouched, so a user who upgraded never loses day history because a
      *  session log was pruned. */
     backfillHours(persistence: UsageSessionPersistence, sessions: UsageSessionStore, signal?: AbortSignal): Promise<void>;
-    /** Shared replay engine behind {@link backfill} and {@link backfillHours}.
-     *  `target` selects the cursor pair, the write function, and the cursor
-     *  the completed sessions land in. */
+    /** The failure upgrade pass: replay every session the FAILURE cursors have
+     *  not seen, counting only failed calls. Neither the day nor the hour
+     *  cursor covers this counter (both were full when it arrived), and the
+     *  replay must not re-add tokens or requests. */
+    backfillFailures(persistence: UsageSessionPersistence, sessions: UsageSessionStore, signal?: AbortSignal): Promise<void>;
+    /** Shared replay engine behind {@link backfill}, {@link backfillHours} and
+     *  {@link backfillFailures}. `target` selects the cursor pair, the write
+     *  function, and the cursor the completed sessions land in. */
     private scan;
 }

package/lib/types/context-types.d.ts

@@ -151,6 +151,22 @@ export interface UsageLlmService {
         id: string;
         name: string;
     }[]>;
+    /** The provider catalog: route id -> the display name the model selector
+     *  shows. Synchronous on every host line this plugin supports (the llm
+     *  runtime's own `listProviders`, mirrored by the dsh-llm service). Optional:
+     *  a host without it leaves every ranked provider row labelled by its raw
+     *  historical route id. */
+    listProviders?(): readonly {
+        id: string;
+        name: string;
+    }[];
+    /** The configured-provider view (the models page's own list), whose
+     *  `displayName` is the same label. Read as a fallback for a route that
+     *  `listProviders` omits. */
+    listConfigurableProviders?(): readonly {
+        provider: string;
+        displayName: string;
+    }[];
 }
 /** The route a session's log records for its model calls (mirror of
  *  dsh-agent-loop RequestContext). */
@@ -167,8 +183,13 @@ export interface UsageSessionHandle {
     id: string;
     cwd?: string;
     createdAt?: number;
-    /** The parent session a subagent session was delegated from (mirror of the
-     *  SessionHeader field; absent on a root session). */
+    /** Modern hosts retain creation metadata on Session.header, not as getters. */
+    header?: UsageSessionHeader;
+    /** Exact fork prefix, distinct from the resume/construction seed length. */
+    inheritedEventCount?: number;
+    /** Immutable current live log; avoids the persistence backend's batching lag. */
+    snapshotEvents?(): readonly UsageSessionEvent[];
+    /** Legacy direct parent; modern hosts expose header.parentSession instead. */
     parentSession?: string;
     /** 0 for a root session; the delegation depth for a subagent. */
     delegationDepth?: number;

package/lib/types/model-names.d.ts

@@ -2,6 +2,12 @@
  *  This is query-time metadata: no store wipe/replay is needed, and a provider
  *  rename applies to both the ranking and every trend bucket on refresh. */
 import type { UsageLlmService } from './context-types.ts';
+/** Resolve provider route ids to the labels the model selector shows. Both
+ *  catalogs are presentational and synchronous on the host runtime, so this is
+ *  a plain in-process read rather than a per-request lookup: a missing service,
+ *  a throwing adapter, or an unexpected promise all resolve to an empty map and
+ *  every surface falls back to the raw historical route id. */
+export declare function resolveProviderNames(llm?: UsageLlmService): Record<string, string>;
 /** Resolve each distinct route once per range query. Unknown/deleted providers
  *  fall back to their bare historical model names in aggregateSamples(). */
 export declare function resolveModelNames(modelRefs: Iterable<string>, llm?: UsageLlmService): Promise<Map<string, string>>;

package/lib/types/query.d.ts

@@ -41,6 +41,14 @@ export interface UsageSample {
     cacheWriteTokens: number;
     turn?: boolean;
     request?: boolean;
+    /** True when this sample also counts one FAILED provider call. The host
+     *  appends `assistant/attempt` (instead of `assistant/message`) when a
+     *  call's stream ends with an error or is cancelled before any content is
+     *  committed, so that event is the exact boundary of a failed call. The
+     *  marker is ORTHOGONAL to `request` and to the buckets: a failed call was
+     *  still opened by its own `step/start` (so it is already one request) and
+     *  a stream that died mid-flight may still report usage. */
+    failed?: boolean;
 }
 export interface RangeFilter {
     from: string;

package/lib/types/session-usage.d.ts

@@ -26,18 +26,17 @@ import type { UsageSessionPersistence, UsageSessionStore } from './context-types
 import type { SessionUsageTree } from './wire.ts';
 export type { SessionUsageTotals, SessionUsageTree } from './wire.ts';
 export declare class SessionUsageService {
-    /** Cached trees, each remembering every session id it was built from, so a
-     *  live event on ANY of them (a subagent's own event changes its ancestors'
-     *  totals too) can invalidate exactly the affected trees. */
+    /** Short-lived tree reads; any live event can invalidate tree membership. */
     private cache;
-    /** Drop every cached tree that counted `sessionId` (its own tree, or any
-     *  ancestor's tree that folded it in as a subagent). Called by the collector
-     *  on each live session event. */
-    invalidate(sessionId: string): void;
+    /** Any event can introduce a new descendant while an async read is running. */
+    private generation;
+    /** Invalidate conservatively: an unseen session may be a newly-created child
+     *  of ANY cached root, so membership-only invalidation is not safe. */
+    invalidate(_sessionId: string): void;
     /** Resolve the whole session tree rooted at `rootId` and sum its usage.
      *  `self` is the root's own usage, `subagents` every descendant's, `total`
-     *  the sum. Unknown roots answer zeroed totals rather than throwing: the pill
-     *  must never break the composer. */
+     *  the sum. Unreadable logs reject rather than publishing partial totals;
+     *  callers can retain their last good display while surfacing the error. */
     tree(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, signal?: AbortSignal): Promise<SessionUsageTree>;
     private listHeaders;
 }

package/lib/types/store.d.ts

@@ -23,6 +23,11 @@ export interface UsageCounters {
     cacheReadTokens: number;
     cacheWriteTokens: number;
     requests: number;
+    /** Provider calls in the bucket that FAILED (error / cancelled before any
+     *  content): a subset of `requests`, never larger than it. Rows persisted
+     *  before the counter existed may lack it; the schema normalizes that to 0
+     *  and every subsequent fold writes the number back. */
+    failures: number;
     turns: number;
     lastSeen: number;
 }
@@ -43,6 +48,7 @@ export declare const usageDayRowSchema: z.ZodObject<{
     cacheReadTokens: z.ZodNumber;
     cacheWriteTokens: z.ZodNumber;
     requests: z.ZodNumber;
+    failures: z.ZodDefault<z.ZodNumber>;
     turns: z.ZodNumber;
     lastSeen: z.ZodNumber;
 }, z.core.$strip>;
@@ -55,6 +61,7 @@ export declare const usageHourRowSchema: z.ZodObject<{
     cacheReadTokens: z.ZodNumber;
     cacheWriteTokens: z.ZodNumber;
     requests: z.ZodNumber;
+    failures: z.ZodDefault<z.ZodNumber>;
     turns: z.ZodNumber;
     lastSeen: z.ZodNumber;
 }, z.core.$strip>;
@@ -81,12 +88,17 @@ export declare const usageHistoryDomain: {
             hoursBackfilledSessions: z.ZodOptional<z.ZodArray<z.ZodString>>;
             hoursLiveFirstSeq: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
             hoursReady: z.ZodOptional<z.ZodBoolean>;
+            failuresBackfilledSessions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            failuresLiveFirstSeq: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+            failuresReady: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>;
         initial: {
             backfilledSessions: string[];
             liveFirstSeq: {};
             hoursBackfilledSessions: string[];
             hoursLiveFirstSeq: {};
+            failuresBackfilledSessions: string[];
+            failuresLiveFirstSeq: {};
         };
     };
     tables: {
@@ -160,6 +172,21 @@ export declare class UsageStore {
     hoursReady(): Promise<boolean>;
     /** Mark the hour history complete; the upgrade pass then never reruns. */
     markHoursReady(): Promise<void>;
+    /** Session ids already replayed into the FAILURE counter (third cursor
+     *  pair, same reason as the hour pair: the day and hour cursors were
+     *  already full when the counter arrived). */
+    failuresSeenSessions(): Promise<Set<string>>;
+    /** Per-session seq of the first LIVE-observed event, failure-counter share. */
+    failuresLiveSequences(): Promise<Map<string, number>>;
+    /** Persist failure-pass replay progress (merges; serialized on the same
+     *  chain as every other cursor write). */
+    markFailuresSeenSessions(ids: Iterable<string>): Promise<void>;
+    /** Record the failure-pass live boundary per session (earliest wins). */
+    markFailuresLiveSequences(entries: Iterable<readonly [string, number]>): Promise<void>;
+    /** Whether the failure counter covers every replayable session. */
+    failuresReady(): Promise<boolean>;
+    /** Mark the failure history complete; the upgrade pass then never reruns. */
+    markFailuresReady(): Promise<void>;
     /** Drop every row and the whole cursor, re-bounding each named session at
      *  its WIPE-TIME WATERMARK (the store-rebuild escape hatch for corrupted
      *  history or attribution-logic upgrades).
@@ -198,6 +225,11 @@ export declare class UsageStore {
      *  day cursors are already advanced, so replaying through `record()` would
      *  double every day row. */
     recordHours(sample: UsageSample): Promise<void>;
+    /** Fold ONLY the failure count of a sample into the day and hour rows. The
+     *  failure upgrade pass uses this: its replay walks logs the token passes
+     *  already consumed, so the tokens and the request marker must not be added
+     *  a second time — only the failed-call counter may move. */
+    recordFailure(sample: UsageSample): Promise<void>;
     /** The row identity a sample lands on: turn markers use the synthetic
      *  (turns) model, unlabelled calls the (unknown) one. */
     private targetsOf;

package/lib/types/wire.d.ts

@@ -17,6 +17,7 @@ export interface DailyTokenUsage {
     byModel: Record<string, number>;
     byProvider: Record<string, number>;
     requests: number;
+    failures: number;
     turns: number;
     cacheHit: number;
     cacheMiss: number;
@@ -29,6 +30,13 @@ export interface ModelTokenUsage {
     provider: string;
     /** All source providers; optional for compatibility with older responses. */
     providers?: string[];
+    /** Per-provider token split of this one model, largest first — the ranked
+     *  row's hover detail ("which providers served this model"). Optional so a
+     *  pre-cross-breakdown host still renders. */
+    providerTokens?: Array<{
+        provider: string;
+        tokens: number;
+    }>;
     tokens: number;
     percent: number;
     /** Cached input tokens this model served (rate numerator). */
@@ -43,6 +51,13 @@ export interface ProviderTokenUsage {
     percent: number;
     cacheHit: number;
     cacheMiss: number;
+    /** Per-model token split this provider served, largest first — the ranked
+     *  row's hover detail ("which models this provider served"). Optional so a
+     *  pre-cross-breakdown host still renders. */
+    modelTokens?: Array<{
+        model: string;
+        tokens: number;
+    }>;
 }
 /** The full aggregate the panel renders for one time range. */
 export interface TokenTotalRange {
@@ -56,6 +71,12 @@ export interface TokenTotalRange {
     /** Cached prompt tokens: cache reads + cache writes (the cache bucket of `tokens`). */
     cacheTokens: number;
     requests: number;
+    /** Provider calls in the range that FAILED: the stream ended with an error
+     *  or the call was cancelled before any content was committed. A subset of
+     *  `requests` (a failed call was still one call), and — like `requests` —
+     *  independent of the token buckets: a stream that died mid-flight may
+     *  still have reported usage. */
+    failures: number;
     turns: number;
     cacheHit: number;
     cacheMiss: number;
@@ -68,6 +89,11 @@ export interface TokenTotalRange {
     daily: DailyTokenUsage[];
     models: ModelTokenUsage[];
     providers: ProviderTokenUsage[];
+    /** Provider route id -> the display name the model selector shows. Filled by
+     *  the host route from the llm service metadata; a provider missing here (a
+     *  deleted route, an older host) renders as its raw id. Optional so a host
+     *  that cannot resolve names still serves a valid payload. */
+    providerNames?: Record<string, string>;
 }
 /** The usage statistics panel aggregate request. */
 export interface TokenTotalRequest {
@@ -87,8 +113,11 @@ export interface SessionUsageTotals {
  *  The composer stats row renders this so a delegating session shows its whole
  *  spend (the native `tokenUsage` projection only covers the main agent). */
 export interface SessionUsageTree {
-    /** The root session's own (main agent) usage. */
+    /** The root session's own usage, including logged compaction calls. */
     self: SessionUsageTotals;
+    /** Root-only compaction spend already included in `self`, but absent from
+     *  the native `tokenUsage` projection. Optional for older host responses. */
+    selfCompaction?: SessionUsageTotals;
     /** Sum over every descendant (subagent) session. */
     subagents: SessionUsageTotals;
     /** self + subagents. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-token-total",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "DSH web plugin: token 用量统计看板 + 单会话（主智能体 + 子智能体）用量统计。提供今日/近3天/近7天/近1月/近3月/自定义筛选、六个汇总卡片、活跃热力图、缓存命中率折线与分模型柱状图、按模型/按供应商 Top5 列表。",
   "icon": "./icon.svg",
   "type": "module",

package/src/client/ContextUsageEntry.module.css

@@ -0,0 +1,20 @@
+.root { display: inline-flex; align-items: center; min-width: 0; font: inherit; font-variant-numeric: tabular-nums; line-height: inherit; }
+.trigger { display: inline-flex; align-items: center; gap: 6px; box-sizing: border-box; max-width: 100%; padding: 1px 8px; border: 0; border-radius: 24px; background: transparent; color: var(--dsw-alias-label-tertiary); font: inherit; line-height: inherit; white-space: nowrap; cursor: pointer; }
+.trigger svg { flex: none; }
+.track { fill: none; stroke: var(--dsw-alias-separator-primary); stroke-width: 1.5; }
+.fill { fill: none; stroke: var(--dsw-alias-label-tertiary); stroke-width: 2; stroke-linecap: round; }
+.trigger:hover, .trigger[aria-expanded='true'] { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-secondary); }
+.panel { position: fixed; z-index: 1100; box-sizing: border-box; width: max-content; min-width: min(300px, calc(100vw - 24px)); max-width: min(440px, calc(100vw - 24px)); padding: 16px; border-radius: 12px; background: var(--dsw-specific-menu); backdrop-filter: var(--dsw-menu-backdrop-filter); box-shadow: var(--dsw-elevation-prominent); color: var(--dsw-alias-label-secondary); font-size: 12px; line-height: 18px; }
+.header { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; color: var(--dsw-alias-label-primary); font-weight: 500; }
+.percent { font-variant-numeric: tabular-nums; }
+.figures { margin-left: auto; color: var(--dsw-alias-label-tertiary); font-variant-numeric: tabular-nums; white-space: nowrap; }
+.bar { display: flex; width: 100%; height: 8px; overflow: hidden; border-radius: 4px; background: var(--dsw-alias-separator-primary); }
+.segment { height: 100%; }
+.systemTokens { background: var(--dsw-alias-label-primary); }
+.toolsTokens { background: var(--dsw-alias-label-secondary); }
+.messageTokens { background: var(--dsw-alias-label-tertiary); }
+.rows { display: grid; gap: 6px; margin: 12px 0 0; color: var(--dsw-alias-label-tertiary); }
+.row { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.row dt { display: flex; align-items: center; gap: 8px; }
+.row dd { margin: 0; color: var(--dsw-alias-label-secondary); font-variant-numeric: tabular-nums; }
+.swatch { width: 8px; height: 8px; border-radius: 2px; }

package/src/client/ContextUsageEntry.tsx

@@ -0,0 +1,89 @@
+import { createPortal } from 'react-dom'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useAnchoredPosition, useDismissOnOutsidePointer } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
+import { MEASURE_STYLE } from './stat-dialog.ts'
+import { contextBreakdownSegments, contextOccupancy, formatContextTokens, type ContextBreakdownLike, type ContextPressureLike } from './context-meter-core.ts'
+import css from './ContextUsageEntry.module.css'
+
+export const CONTEXT_LOCALE_NS = 'tokenTotalContext'
+const keys = ['label', 'used', 'system', 'tools', 'messages', 'aria', 'thousand', 'million'] as const
+export type ContextLocaleKey = typeof keys[number]
+export const CONTEXT_LOCALES: Record<string, Record<ContextLocaleKey, string>> = {
+  zh: { label: '上下文', used: '已用上下文', system: '系统提示词', tools: '工具', messages: '对话', aria: '上下文占用 {percent}', thousand: '{value}千', million: '{value}百万' },
+  en: { label: 'Context', used: 'Context used', system: 'System', tools: 'Tools', messages: 'Conversation', aria: 'Context usage {percent}', thousand: '{value}K', million: '{value}M' },
+  'zh-TW': { label: '上下文', used: '已用上下文', system: '系統提示詞', tools: '工具', messages: '對話', aria: '上下文使用量 {percent}', thousand: '{value}千', million: '{value}百萬' },
+}
+
+type ProjectionMap = {
+  contextPressure: ContextPressureLike
+  contextBreakdown: ContextBreakdownLike
+}
+type UseContextProjection = <K extends keyof ProjectionMap & string>(key: K) => ProjectionMap[K] | undefined
+
+export interface ContextUsageEntryProps extends PropsLocale<typeof CONTEXT_LOCALE_NS> {
+  useProjection: UseContextProjection
+  installContextTakeover?: (anchor: HTMLElement) => () => void
+}
+
+export function ContextUsageEntry({ useProjection, t, installContextTakeover }: ContextUsageEntryProps): JSX.Element | null {
+  const pressure = useProjection('contextPressure')
+  const breakdown = useProjection('contextBreakdown')
+  const context = contextOccupancy(pressure)
+  const [open, setOpen] = useState(false)
+  const rootRef = useRef<HTMLSpanElement | null>(null)
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const position = useAnchoredPosition({ open: open && context !== null, anchorRef: rootRef, panelRef, side: 'top', gap: 8, margin: 12 })
+  useDismissOnOutsidePointer(rootRef, open && context !== null, setOpen, panelRef)
+  useLayoutEffect(() => {
+    const anchor = rootRef.current
+    if (anchor === null || context === null || installContextTakeover === undefined) return
+    return installContextTakeover(anchor)
+  }, [context !== null, installContextTakeover])
+  useEffect(() => { if (context === null && open) setOpen(false) }, [context, open])
+  useEffect(() => {
+    if (!open || context === null) return
+    const onKeyDown = (event: KeyboardEvent): void => { if (event.key === 'Escape') setOpen(false) }
+    document.addEventListener('keydown', onKeyDown)
+    return () => document.removeEventListener('keydown', onKeyDown)
+  }, [context, open])
+  if (context === null) return null
+  const percent = context.percent
+  const reading = `${percent}%`
+  const total = breakdown === undefined ? 0 : breakdown.systemTokens + breakdown.toolsTokens + breakdown.messageTokens
+  const segments = contextBreakdownSegments(percent, breakdown)
+  const format = (value: number): string => formatContextTokens(value, {
+    thousand: t('thousand'), million: t('million'),
+  })
+  const label = (part: 'system' | 'tools' | 'messages'): string => t(part)
+  return (
+    <span ref={rootRef} className={css.root} data-dsh-token-total-stat="context">
+      <button type="button" className={css.trigger} aria-label={t('aria', { percent: reading })} aria-haspopup="dialog" aria-expanded={open} onClick={() => setOpen(!open)}>
+        <svg viewBox="0 0 14 14" width="14" height="14" aria-hidden="true">
+          <circle className={css.track} cx="7" cy="7" r="5.5" />
+          <circle className={css.fill} cx="7" cy="7" r="5.5" strokeDasharray={`${2 * Math.PI * 5.5 * percent / 100} ${2 * Math.PI * 5.5}`} transform="rotate(-90 7 7)" />
+        </svg>
+        <span>{reading}</span>
+      </button>
+      {open && createPortal(
+        <div ref={panelRef} className={css.panel} style={position ?? MEASURE_STYLE} role="dialog" aria-label={t('used')}>
+          <div className={css.header}>
+            <span>{t('used')}</span><span className={css.percent}>{reading}</span>
+            <span className={css.figures}>{`~${format(context.usedTokens)} / ${format(context.contextWindow)}`}</span>
+          </div>
+          <div className={css.bar}>{segments.map(segment => <div key={segment.key} className={`${css.segment} ${css[segment.key] ?? ''}`} style={{ width: `${segment.width}%` }} />)}</div>
+          {breakdown !== undefined && total > 0 && <dl className={css.rows}>
+            {(['systemTokens', 'toolsTokens', 'messageTokens'] as const).map((key, index) => <div className={css.row} key={key}>
+              <dt><span className={`${css.swatch} ${css[key]}`} />{label((['system', 'tools', 'messages'] as const)[index])}</dt>
+              <dd>{`~${format(breakdown[key])}`}</dd>
+            </div>)}
+          </dl>}
+        </div>, document.body,
+      )}
+    </span>
+  )
+}
+
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+  interface LocaleNamespaceMap { tokenTotalContext: ContextLocaleKey }
+}