dsh-token-total 1.1.0 → 1.1.2

package/src/client/UsageCards.tsx

@@ -0,0 +1,244 @@
+/**
+ * The two cards that replaced the context-window panel.
+ *
+ * Left: what the window holds RIGHT NOW (the context snapshot). Right: what the
+ * session's requests actually spent, split by content (the spend composition).
+ * They answer two different questions — "what is in the prompt" and "what did
+ * the whole session pay for" — so they sit side by side at equal weight rather
+ * than one above the other.
+ *
+ * Everything is drawn from the detail payload the view already polls every
+ * 1.5 s (`useSessionDetail`), so both cards refresh with no extra timer. The
+ * charts are hand-rolled SVG/CSS: the plugin ships no chart dependency, and a
+ * ring plus a stacked bar is little enough markup to keep it that way.
+ *
+ * The palette is the plugin's tone scale, matching the stat cards above and the
+ * dashboard charts; dark values flip under `body[data-ds-dark-theme]` (the
+ * host's own theme switch), and every surface uses the host's semantic tokens
+ * so the cards sit on the same canvas as the tables.
+ */
+import type {
+  SessionContextWindow,
+  SessionUsageBucket,
+  SessionUsageComposition,
+  SessionUsageDetail,
+} from '../wire.ts'
+import { bucketPercent, contextBucketTotals, contextReading } from './context-window-core.ts'
+import { cacheRate, formatCompact, formatPercent, formatTokens } from './format.ts'
+import { cacheHitPercentOf } from './session-usage-core.ts'
+import type { SessionUsageKey } from './session-usage-locales.ts'
+import { CONTEXT_BUCKET_ORDER, USAGE_BUCKET_ORDER } from '../usage-buckets.ts'
+import css from './UsageCards.module.css'
+
+type T = (key: SessionUsageKey, params?: Record<string, string>) => string
+
+/** Legend names, one per bucket (the context-window panel's category names are
+ *  a different split — files live inside tool results here). */
+const BUCKET_LABEL: Record<SessionUsageBucket, SessionUsageKey> = {
+  systemPrompt: 'bucketSystemPrompt',
+  user: 'bucketUser',
+  skill: 'bucketSkill',
+  toolResult: 'bucketToolResult',
+  toolDef: 'bucketToolDef',
+  injected: 'bucketInjected',
+  assistant: 'bucketAssistant',
+  output: 'bucketOutput',
+}
+
+/** Each bucket brings its own accent as a CSS custom property, so the swatch,
+ *  the ring segment, the bar segment and the value text all read one variable. */
+const BUCKET_TONE: Record<SessionUsageBucket, string> = {
+  systemPrompt: css.toneSystemPrompt,
+  user: css.toneUser,
+  skill: css.toneSkill,
+  toolResult: css.toneToolResult,
+  toolDef: css.toneToolDef,
+  injected: css.toneInjected,
+  assistant: css.toneAssistant,
+  output: css.toneOutput,
+}
+
+interface Row {
+  key: SessionUsageBucket
+  tokens: number
+}
+
+/** Approximate value as the card prints it: "≈299.1k". */
+const approx = (n: number): string => `≈${formatCompact(n)}`
+
+/** Ring geometry: a 116 px donut with a 15 px stroke. */
+const RING_SIZE = 116
+const RING_STROKE = 15
+const RING_RADIUS = (RING_SIZE - RING_STROKE) / 2 - 2
+const RING_CIRCUMFERENCE = 2 * Math.PI * RING_RADIUS
+
+/** Donut of bucket shares with the grand total in the middle. Segments are
+ *  stroked along one circle and offset by the running length, so the ring is
+ *  DPI-independent and needs no chart library. `total` sizes the segments (the
+ *  replay estimate); `center` is the exact billed figure the card headlines. */
+function Ring({ rows, total, center, centerTitle, caption }: {
+  rows: readonly Row[]
+  total: number
+  center: string
+  centerTitle: string
+  caption: string
+}): JSX.Element {
+  const drawn = rows.filter(row => row.tokens > 0)
+  let offset = 0
+  return <div className={css.ringWrap}>
+    <svg className={css.ring} width={RING_SIZE} height={RING_SIZE} viewBox={`0 0 ${RING_SIZE} ${RING_SIZE}`} role="img" aria-label={caption}>
+      <title>{caption}</title>
+      <circle className={css.ringTrack} cx={RING_SIZE / 2} cy={RING_SIZE / 2} r={RING_RADIUS} fill="none" strokeWidth={RING_STROKE} />
+      <g transform={`rotate(-90 ${RING_SIZE / 2} ${RING_SIZE / 2})`}>
+        {drawn.map(row => {
+          const length = total > 0 ? (row.tokens / total) * RING_CIRCUMFERENCE : 0
+          // A hairline gap keeps adjacent hues from merging into one band; the
+          // segment never shrinks below 0.6 px even when it is a rounding crumb.
+          const visible = Math.max(length - 1.2, 0.6)
+          const dash = `${visible} ${RING_CIRCUMFERENCE - visible}`
+          const circle = <circle
+            key={row.key}
+            className={BUCKET_TONE[row.key]}
+            cx={RING_SIZE / 2}
+            cy={RING_SIZE / 2}
+            r={RING_RADIUS}
+            fill="none"
+            stroke="var(--bucket)"
+            strokeWidth={RING_STROKE}
+            strokeDasharray={dash}
+            strokeDashoffset={-offset}
+          />
+          offset += length
+          return circle
+        })}
+      </g>
+    </svg>
+    <div className={css.ringCenter}>
+      <strong className={css.ringTotal} title={centerTitle}>{center}</strong>
+      <span className={css.ringCaption}>{caption}</span>
+    </div>
+  </div>
+}
+
+/** One legend entry: swatch, name, share, approximate value. */
+function LegendRow({ row, percent, suffix, t }: {
+  row: Row
+  percent: number
+  suffix?: string
+  t: T
+}): JSX.Element {
+  return <li className={`${css.legendRow} ${BUCKET_TONE[row.key]}`}>
+    <i className={css.swatch} aria-hidden="true" />
+    <span className={css.legendName}>{t(BUCKET_LABEL[row.key])}</span>
+    <span className={css.legendPercent}>{percent.toFixed(1)}%</span>
+    <span className={css.legendValue} title={formatTokens(row.tokens)}>
+      {approx(row.tokens)}{suffix === undefined ? '' : <span className={css.legendSuffix}> · {suffix}</span>}
+    </span>
+  </li>
+}
+
+/** Left card: the live window's composition, its occupancy and the hard cap. */
+function ContextCard({ context, t }: { context: SessionContextWindow; t: T }): JSX.Element {
+  const reading = contextReading(context)
+  const rows = contextBucketTotals(context.items)
+  // Percentages answer "what share of the window's content", so they divide by
+  // the sum of the drawn buckets — not by the billed prompt, which can differ
+  // when upstream content rewriting happens. Occupancy keeps its own reading.
+  const total = rows.reduce((sum, row) => sum + row.tokens, 0)
+  // The strip spans the model's window, never just the used part: each segment
+  // takes its share of the drawn content times the share of the window in use,
+  // so the tinted run stops exactly where "used" stops and the track behind it
+  // is the room still free. Without a reported window there is no scale to draw
+  // against, so the strip falls back to the drawn content itself.
+  const capacity = context.contextWindow !== null && context.contextWindow > 0 ? context.contextWindow : total
+  const occupied = Math.min(100, bucketPercent(reading.usedTokens, capacity))
+  const windowText = context.contextWindow !== null && context.contextWindow > 0
+    ? t('contextWindowTotal', { used: formatCompact(reading.usedTokens), window: formatCompact(context.contextWindow) })
+    : t('contextWindowTotalUnknown', { used: formatCompact(reading.usedTokens) })
+  return <section className={`${css.card} ${css.contextCard}`}>
+    <header className={css.head}>
+      <h2 className={css.title}>{t('currentContextTitle')}</h2>
+      <span className={css.model} title={`${context.provider} / ${context.model}`}>
+        {[context.provider, context.model].filter(Boolean).join(' · ') || '—'}
+      </span>
+    </header>
+    <div className={css.body}>
+      <div className={css.totalRow}>
+        <strong className={css.total} title={formatTokens(reading.usedTokens)}>{windowText}</strong>
+        {reading.percent !== null && <span className={css.totalShare}>
+          <b>{formatPercent(reading.percent)}</b> {t('contextUsedShort')}
+        </span>}
+      </div>
+      {/* One stacked strip across the whole window: a bucket's width is its
+          share of what the next request carries, scaled by how full the window
+          is, so the remainder reads as the room still free. */}
+      <div className={css.bar} role="img" aria-label={t('currentContextTitle')}>
+        {rows.map(row => row.tokens > 0 && total > 0
+          ? <span key={row.key} className={`${css.barSeg} ${BUCKET_TONE[row.key]}`} style={{ width: `${bucketPercent(row.tokens, total) * occupied / 100}%` }} />
+          : null)}
+        {total <= 0 && <span className={css.barEmpty} />}
+      </div>
+      <ul className={css.legend}>
+        {rows.map(row => <LegendRow key={row.key} row={row} percent={bucketPercent(row.tokens, total)} t={t} />)}
+      </ul>
+    </div>
+  </section>
+}
+
+/** Right card: every request's replayed content plus the billed output. */
+function StatsCard({ detail, t }: { detail: SessionUsageDetail; t: T }): JSX.Element {
+  const composition = detail.composition ?? null
+  const rows = composition?.buckets ?? []
+  const total = rows.reduce((sum, row) => sum + row.tokens, 0)
+  const billed = composition?.billedTokens ?? 0
+  // Prefer the session's exact cache split; the live window's snapshot is the
+  // fallback for an older host payload that predates the composition.
+  const hit = composition !== null
+    ? cacheHitPercentOf(composition.totals)
+    : detail.context?.cacheKnown
+      ? cacheRate(detail.context.cacheHitTokens, detail.context.cacheMissTokens)
+      : null
+  return <section className={`${css.card} ${css.statsCard}`}>
+    <header className={css.head}>
+      <h2 className={css.title}>{t('statsTitle')}</h2>
+      {hit !== null && <span className={css.cacheBadge}>
+        {t('statsCacheHit')} <b>{hit.toFixed(2)}%</b>
+      </span>}
+    </header>
+    <div className={css.body}>
+      {composition === null
+        ? <p className={css.empty}>{t('statsEmpty')}</p>
+        : <>
+          <div className={css.statsMain}>
+            <Ring rows={rows} total={total} center={formatCompact(billed)} centerTitle={formatTokens(billed)} caption={t('statsTotal')} />
+            <ul className={css.legend}>
+              {USAGE_BUCKET_ORDER.map(key => {
+                const row = rows.find(item => item.key === key) ?? { key, tokens: 0 }
+                return <LegendRow
+                  key={key}
+                  row={row}
+                  percent={bucketPercent(row.tokens, total)}
+                  suffix={key === 'output' ? t('statsIncludesThinking') : undefined}
+                  t={t}
+                />
+              })}
+            </ul>
+          </div>
+        </>}
+    </div>
+  </section>
+}
+
+/** The pair, rendered where the context-window panel used to sit. */
+export function SessionUsageCards({ detail, t }: { detail: SessionUsageDetail; t: T }): JSX.Element | null {
+  if (detail.context === null || detail.context === undefined) {
+    if (detail.composition === null || detail.composition === undefined) return null
+    return <div className={css.grid}>
+      <StatsCard detail={detail} t={t} />
+    </div>
+  }
+  return <div className={css.grid}>
+    <ContextCard context={detail.context} t={t} />
+    <StatsCard detail={detail} t={t} />
+  </div>
+}

package/src/client/context-window-core.ts

@@ -4,6 +4,8 @@
  * separate from the component so both are testable without a DOM.
  */
 import type { SessionContextCategory, SessionContextItem, SessionContextWindow } from '../wire.ts'
+import type { SessionUsageBucket } from '../wire.ts'
+import { CONTEXT_BUCKET_ORDER } from '../usage-buckets.ts'
 
 /** Legend order, also the color assignment order (see the CSS module). */
 export const CONTEXT_CATEGORY_ORDER: readonly SessionContextCategory[] = [
@@ -30,6 +32,43 @@ export function contextCategoryTotals(
     .filter(row => row.tokens > 0)
 }
 
+/** Which legend bucket one window row belongs to.
+ *
+ *  The row categories are the treemap's (they group files separately); the
+ *  cards speak the eight-bucket legend instead. A folded `rest` row lost its
+ *  kind, so a conversation tail lands with the assistant — the larger half of
+ *  what a turn replays.
+ */
+function contextBucketOf(item: SessionContextItem): SessionUsageBucket {
+  switch (item.category) {
+    case 'system': return 'systemPrompt'
+    case 'tools': return 'toolDef'
+    case 'memory': return item.kind === 'skill-catalog' ? 'skill' : 'injected'
+    case 'files':
+    case 'results': return 'toolResult'
+    case 'conversation': return item.kind === 'user' ? 'user' : 'assistant'
+    default: return 'injected'
+  }
+}
+
+/** The live window folded into the same legend the spend card prints, in
+ *  legend order and keeping zero buckets so both cards stay aligned. */
+export function contextBucketTotals(
+  items: readonly SessionContextItem[],
+): Array<{ key: SessionUsageBucket; tokens: number }> {
+  const totals = new Map<SessionUsageBucket, number>()
+  for (const item of items) {
+    const key = contextBucketOf(item)
+    totals.set(key, (totals.get(key) ?? 0) + item.tokens)
+  }
+  return CONTEXT_BUCKET_ORDER.map(key => ({ key, tokens: totals.get(key) ?? 0 }))
+}
+
+/** What a share of the whole is, for the legend column. */
+export function bucketPercent(tokens: number, total: number): number {
+  return total > 0 ? (tokens / total) * 100 : 0
+}
+
 /** Window occupancy in whole percent, or null when the host never reported the
  *  model's window (the panel then says "unknown" instead of guessing one). */
 export function contextWindowPercent(usedTokens: number, contextWindow: number | null): number | null {

package/src/client/session-usage-locales.ts

@@ -16,7 +16,7 @@ export const usageZh = {
   answering: '正在回答...', firstWait: '首字耗时', sec: '秒', tokenWord: 'token', perSec: 'token/秒',
   cacheShort: '缓存', avgCache: '平均缓存', avgRate: '平均速率', inProgress: '个进行中',
   live: '实时更新', asOf: '统计截至', refresh: '刷新',
-  contextTitle: '上下文窗口', contextUsed: '已用上下文', contextLive: '实时',
+  contextTitle: '上下文窗口', currentContextTitle: '当前上下文', contextUsed: '已用上下文', contextLive: '实时',
   contextWindowKnown: '模型窗口 {value} · 已用 {percent}%', contextWindowUnknown: '模型的窗口大小未知',
   contextDigest: '{used} / {window} · {percent}%', contextDigestUnknown: '{used} / 窗口未知',
   contextFree: '空闲',
@@ -30,6 +30,14 @@ export const usageZh = {
   contextKindRest: '另外 {count} 项', contextTimes: '×{count}',
   contextEmpty: '本会话还没有可统计的上下文', contextTipShare: '占上下文 {percent}', contextTipWindow: '占窗口 {percent}',
   contextEstimateNote: '色块按历史重放估算 {estimate}；供应商实测提示词 {billed}（上游已压缩或裁剪）',
+  // ── The two cards that replaced the context-window panel ──────────────────
+  statsTitle: 'Token 统计', statsTotal: '总用量', statsCacheHit: '缓存命中',
+  statsIncludesThinking: '含思考', statsEmpty: '本会话还没有可统计的 token',
+  contextWindowTotal: '{used} / {window} tokens', contextWindowTotalUnknown: '{used} tokens',
+  contextUsedShort: '上下文已用',
+  bucketSystemPrompt: '系统提示词', bucketUser: '用户消息', bucketSkill: '技能注入',
+  bucketToolResult: '工具结果', bucketToolDef: '工具定义', bucketInjected: '注入内容',
+  bucketAssistant: '助手消息', bucketOutput: '输出',
 }
 export type SessionUsageKey = keyof typeof usageZh
 export const usageEn: Record<SessionUsageKey, string> = {
@@ -48,7 +56,7 @@ export const usageEn: Record<SessionUsageKey, string> = {
   answering: 'answering...', firstWait: 'first token', sec: 's', tokenWord: 'token', perSec: 'token/s',
   cacheShort: 'cache', avgCache: 'avg cache', avgRate: 'avg rate', inProgress: 'in progress',
   live: 'Live', asOf: 'as of', refresh: 'Refresh',
-  contextTitle: 'Context window', contextUsed: 'Context used', contextLive: 'Live',
+  contextTitle: 'Context window', currentContextTitle: 'Current context', contextUsed: 'Context used', contextLive: 'Live',
   contextWindowKnown: 'Window {value} · {percent}% used', contextWindowUnknown: 'Model window size unknown',
   contextDigest: '{used} / {window} · {percent}%', contextDigestUnknown: '{used} / window unknown',
   contextFree: 'free',
@@ -62,6 +70,14 @@ export const usageEn: Record<SessionUsageKey, string> = {
   contextKindRest: '{count} more', contextTimes: '×{count}',
   contextEmpty: 'Nothing in this session’s context yet', contextTipShare: '{percent} of context', contextTipWindow: '{percent} of window',
   contextEstimateNote: 'Blocks estimate {estimate} by replay; the provider billed {billed} after upstream compression',
+  // ── The two cards that replaced the context-window panel ──────────────────
+  statsTitle: 'Token stats', statsTotal: 'Total usage', statsCacheHit: 'Cache hit',
+  statsIncludesThinking: 'incl. thinking', statsEmpty: 'No token spend recorded for this session yet',
+  contextWindowTotal: '{used} / {window} tokens', contextWindowTotalUnknown: '{used} tokens',
+  contextUsedShort: 'context used',
+  bucketSystemPrompt: 'System prompt', bucketUser: 'User messages', bucketSkill: 'Skill injection',
+  bucketToolResult: 'Tool results', bucketToolDef: 'Tool definitions', bucketInjected: 'Injected content',
+  bucketAssistant: 'Assistant messages', bucketOutput: 'Output',
 }
 export const usageZhTW: Record<SessionUsageKey, string> = {
   ...usageZh,
@@ -78,7 +94,7 @@ export const usageZhTW: Record<SessionUsageKey, string> = {
   answering: '正在回答...', firstWait: '首字耗時', sec: '秒', tokenWord: 'token', perSec: 'token/秒',
   cacheShort: '快取', avgCache: '平均快取', avgRate: '平均速率', inProgress: '個進行中',
   live: '即時更新', asOf: '統計截至', refresh: '重新整理',
-  contextTitle: '上下文視窗', contextUsed: '已用上下文', contextLive: '即時',
+  contextTitle: '上下文視窗', currentContextTitle: '當前上下文', contextUsed: '已用上下文', contextLive: '即時',
   contextWindowKnown: '模型視窗 {value} · 已用 {percent}%', contextWindowUnknown: '模型的視窗大小未知',
   contextDigest: '{used} / {window} · {percent}%', contextDigestUnknown: '{used} / 視窗未知',
   contextFree: '空閒',
@@ -92,4 +108,12 @@ export const usageZhTW: Record<SessionUsageKey, string> = {
   contextKindRest: '另外 {count} 項', contextTimes: '×{count}',
   contextEmpty: '本會話還沒有可統計的上下文', contextTipShare: '佔上下文 {percent}', contextTipWindow: '佔視窗 {percent}',
   contextEstimateNote: '色塊按歷史重放估算 {estimate}；供應商實測提示詞 {billed}（上游已壓縮或裁剪）',
+  // ── The two cards that replaced the context-window panel ──────────────────
+  statsTitle: 'Token 統計', statsTotal: '總用量', statsCacheHit: '快取命中',
+  statsIncludesThinking: '含思考', statsEmpty: '本會話還沒有可統計的 token',
+  contextWindowTotal: '{used} / {window} tokens', contextWindowTotalUnknown: '{used} tokens',
+  contextUsedShort: '上下文已用',
+  bucketSystemPrompt: '系統提示詞', bucketUser: '使用者訊息', bucketSkill: '技能注入',
+  bucketToolResult: '工具結果', bucketToolDef: '工具定義', bucketInjected: '注入內容',
+  bucketAssistant: '助手訊息', bucketOutput: '輸出',
 }

package/src/client/stats-line-core.ts

@@ -314,16 +314,25 @@ const CJK_TOKENS_PER_CHAR = 0.6
 const ASCII_TOKENS_PER_CHAR = 0.3
 
 /**
- * Shortest observable decode window before a live rate is published, in ms
- * (the same floor MiMo-Code's sidebar tps uses). Below it the first chunk's
- * burst would read as hundreds of tok/s; the sampler also publishes its FIRST
- * reading at exactly this mark rather than at the next steady cadence.
+ * Shortest observable decode window before a live rate is published, in ms.
+ * Below it the first chunk's burst would read as hundreds of tok/s; the
+ * sampler also publishes its FIRST reading at exactly this mark rather than at
+ * the next steady cadence.
+ *
+ * The floor is deliberately short — 200 ms, down from the 500 ms MiMo-Code's
+ * sidebar tps holds — because every step opens a window of its own, and at
+ * 500 ms a step that finishes inside the floor never published at all: a run
+ * of short steps (one burst of tool-call arguments, then settle) kept showing
+ * a figure measured somewhere else while the screen was full of live output.
+ * At this length the opening burst is judged by the plausibility check below
+ * rather than by waiting it out, and the smoothing constant still carries the
+ * first reading only part of the way into an established figure.
  *
  * The floor is a publishing gate, NOT a rejection gate: it is applied after the
  * plausibility check below, so a backlog frame can never dodge that check by
  * arriving early (see {@link StreamingRateSampler.observe}).
  */
-const MIN_STREAM_WINDOW_MS = 500
+const MIN_STREAM_WINDOW_MS = 200
 
 /**
  * Longest window a live rate may span, in ms. This is the bound the previous

package/src/context-window.ts

@@ -132,6 +132,18 @@ function promptTokensOf(usage: unknown): number | null {
   return input + cached > 0 ? input + cached : null
 }
 
+/** Prompt tokens one tool definition costs: its name, description and JSON
+ *  schema, plus the framing every schema node pays. 0 for a nameless entry.
+ *  Shared with the spend composition, which replays the same catalogue on
+ *  every request. */
+export function toolTokens(tool: unknown): number {
+  const record = tool as { name?: unknown; description?: unknown; parameters?: unknown }
+  const name = String(record?.name ?? '')
+  if (name === '') return 0
+  return estimateTokens(name) + valueTokens(record?.description)
+    + estimateTokens(JSON.stringify(record?.parameters ?? {})) + TOOL_SCHEMA_OVERHEAD_TOKENS
+}
+
 /** Fold one category's rows: keep the biggest until KEEP_SHARE is covered (and
  *  never more than MAX_ROWS_PER_CATEGORY), then merge the tail into one row so
  *  a session with 200 tool calls still yields a readable treemap. */
@@ -279,11 +291,9 @@ export function buildSessionContextWindow(events: readonly UsageSessionEvent[]):
   }
   // The tool catalogue the next call sends: name + description + JSON schema.
   for (const tool of tools) {
-    const record = tool as { name?: unknown; description?: unknown; parameters?: unknown }
-    const name = String(record?.name ?? '')
-    if (name === '') continue
-    const tokens = estimateTokens(name) + valueTokens(record?.description)
-      + estimateTokens(JSON.stringify(record?.parameters ?? {})) + TOOL_SCHEMA_OVERHEAD_TOKENS
+    const tokens = toolTokens(tool)
+    const name = String((tool as { name?: unknown })?.name ?? '')
+    if (name === '' || tokens === 0) continue
     add('tools', name, tokens)
   }
   const items = foldDrafts([...drafts.values()])

package/src/session-detail.ts

@@ -9,6 +9,7 @@ import type {
 } from './context-types.ts'
 import { UsageFold } from './collector.ts'
 import { buildSessionContextWindow } from './context-window.ts'
+import { buildSessionUsageComposition, mergeUsageCompositions } from './usage-composition.ts'
 import { resolveModelNames, resolveProviderNames } from './model-names.ts'
 import { decodeRateOf } from './shared.ts'
 import type { SessionUsageDetail, SessionUsageTotals } from './wire.ts'
@@ -209,7 +210,7 @@ async function one(p: UsageSessionPersistence, id: string, header: UsageSessionH
   // a cancelled step is not a wait the reader experienced as an answer.
   const firsts = records.filter(x => x.status === 'completed').map(x => x.firstTokenMs).filter((x): x is number => x !== null)
   for (const x of records) { x.turnName = turnTopics.get(x.turn) ?? ''; delete (x as any)._attempt; delete (x as any)._lastUsage }
-  return { id, name, header, totals, records: records as SessionUsageDetail['records'], requests, averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null, tokensPerSecond: decodeRateOf(records), context: buildSessionContextWindow(own) }
+  return { id, name, header, totals, records: records as SessionUsageDetail['records'], requests, averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null, tokensPerSecond: decodeRateOf(records), context: buildSessionContextWindow(own), composition: buildSessionUsageComposition(own) }
 }
 
 export async function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail> {
@@ -247,5 +248,5 @@ export async function buildSessionUsageDetail(persistence: UsageSessionPersisten
   // The card is scoped to this session and every subagent, so its speed and
   // first-token average fold the same records its token totals do.
   const firsts = records.filter(x => x.status === 'completed').map(x => x.firstTokenMs).filter((x): x is number => x !== null)
-  return { sessionId: rootId, totals, requests: parts.reduce((n, p) => n + p.requests, 0), averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null, tokensPerSecond: decodeRateOf(records), subagents, models: [...models.entries()].map(([model, x]) => { const name = displayNameOf(model, x.providers); return { model, ...(name ? { name } : {}), providers: [...x.providers].map(provider => providerNames[provider] || provider), totals: x.totals, requests: x.requests } }), records, routes: [...routeMap.values()], context: parts[0]?.context ?? null }
+  return { sessionId: rootId, totals, requests: parts.reduce((n, p) => n + p.requests, 0), averageFirstTokenMs: firsts.length ? firsts.reduce((a, b) => a + b, 0) / firsts.length : null, tokensPerSecond: decodeRateOf(records), subagents, models: [...models.entries()].map(([model, x]) => { const name = displayNameOf(model, x.providers); return { model, ...(name ? { name } : {}), providers: [...x.providers].map(provider => providerNames[provider] || provider), totals: x.totals, requests: x.requests } }), records, routes: [...routeMap.values()], context: parts[0]?.context ?? null, composition: mergeUsageCompositions(parts.map(p => p.composition)) }
 }

package/src/usage-buckets.ts

@@ -0,0 +1,27 @@
+/**
+ * The legend order of the Token stats card, shared by the host accumulator and
+ * the client card so the two halves can never disagree about which bucket sits
+ * where. Left column first (what filled the prompt), right column second: the
+ * layout mirrors the reference design — system/user/skill/results on the left,
+ * tool definitions/injected/assistant/output on the right.
+ *
+ * Kept in its own dependency-free module: the host builds the numbers and the
+ * client paints them, and neither should pull the other's graph in for this.
+ */
+import type { SessionUsageBucket } from './wire.ts'
+
+export const USAGE_BUCKET_ORDER: readonly SessionUsageBucket[] = [
+  'systemPrompt',
+  'user',
+  'skill',
+  'toolResult',
+  'toolDef',
+  'injected',
+  'assistant',
+  'output',
+]
+
+/** The buckets that describe the live window (output never occupies it). */
+export const CONTEXT_BUCKET_ORDER: readonly SessionUsageBucket[] = USAGE_BUCKET_ORDER.filter(
+  (key) => key !== 'output',
+)