dsh-token-total 1.0.3 → 1.0.5

package/src/client/locales.ts

@@ -43,6 +43,25 @@ export type TokenTotalKey =
   | 'heatmap'
   | 'heatLess'
   | 'heatMore'
+  | 'dow.mon'
+  | 'dow.tue'
+  | 'dow.wed'
+  | 'dow.thu'
+  | 'dow.fri'
+  | 'dow.sat'
+  | 'dow.sun'
+  | 'month.jan'
+  | 'month.feb'
+  | 'month.mar'
+  | 'month.apr'
+  | 'month.may'
+  | 'month.jun'
+  | 'month.jul'
+  | 'month.aug'
+  | 'month.sep'
+  | 'month.oct'
+  | 'month.nov'
+  | 'month.dec'
   | 'dailyTrend'
   | 'hourlyTrend'
   | 'trendLimited'
@@ -112,6 +131,25 @@ export const en: Record<TokenTotalKey, string> = {
   heatmap: 'Activity heatmap',
   heatLess: 'Less',
   heatMore: 'More',
+  'dow.mon': 'Mon',
+  'dow.tue': 'Tue',
+  'dow.wed': 'Wed',
+  'dow.thu': 'Thu',
+  'dow.fri': 'Fri',
+  'dow.sat': 'Sat',
+  'dow.sun': 'Sun',
+  'month.jan': 'Jan',
+  'month.feb': 'Feb',
+  'month.mar': 'Mar',
+  'month.apr': 'Apr',
+  'month.may': 'May',
+  'month.jun': 'Jun',
+  'month.jul': 'Jul',
+  'month.aug': 'Aug',
+  'month.sep': 'Sep',
+  'month.oct': 'Oct',
+  'month.nov': 'Nov',
+  'month.dec': 'Dec',
   dailyTrend: 'Daily token trend',
   hourlyTrend: 'Hourly token trend',
   trendLimited: 'Showing the latest {n} days',
@@ -182,6 +220,25 @@ export const zh: Record<TokenTotalKey, string> = {
   heatmap: '活跃热力图',
   heatLess: '较少',
   heatMore: '较多',
+  'dow.mon': '周一',
+  'dow.tue': '周二',
+  'dow.wed': '周三',
+  'dow.thu': '周四',
+  'dow.fri': '周五',
+  'dow.sat': '周六',
+  'dow.sun': '周日',
+  'month.jan': '1月',
+  'month.feb': '2月',
+  'month.mar': '3月',
+  'month.apr': '4月',
+  'month.may': '5月',
+  'month.jun': '6月',
+  'month.jul': '7月',
+  'month.aug': '8月',
+  'month.sep': '9月',
+  'month.oct': '10月',
+  'month.nov': '11月',
+  'month.dec': '12月',
   dailyTrend: '按天 Token 趋势',
   hourlyTrend: '按小时 Token 趋势',
   trendLimited: '仅显示最近 {n} 天',
@@ -252,6 +309,25 @@ export const zhTW: Record<TokenTotalKey, string> = {
   heatmap: '活躍熱力圖',
   heatLess: '較少',
   heatMore: '較多',
+  'dow.mon': '週一',
+  'dow.tue': '週二',
+  'dow.wed': '週三',
+  'dow.thu': '週四',
+  'dow.fri': '週五',
+  'dow.sat': '週六',
+  'dow.sun': '週日',
+  'month.jan': '1月',
+  'month.feb': '2月',
+  'month.mar': '3月',
+  'month.apr': '4月',
+  'month.may': '5月',
+  'month.jun': '6月',
+  'month.jul': '7月',
+  'month.aug': '8月',
+  'month.sep': '9月',
+  'month.oct': '10月',
+  'month.nov': '11月',
+  'month.dec': '12月',
   dailyTrend: '每日 Token 趨勢',
   hourlyTrend: '每小時 Token 趨勢',
   trendLimited: '僅顯示最近 {n} 天',

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

@@ -0,0 +1,50 @@
+/** Session Usage view translations, independent of the global dashboard. */
+export const SESSION_USAGE_NS = 'sessionUsage'
+export const usageZh = {
+  tab: '用量', requests: '请求数', tokens: '总 tokens', hit: '命中率', first: '平均首 token', speed: 'token 速度',
+  input: '入', output: '出', read: '读', write: '写',
+  requestsCount: '请求数量', inputFull: '输入', outputFull: '输出', readFull: '缓存读取', writeFull: '缓存写入',
+  cacheHit: '缓存命中', compaction: '压缩调用', reqTimes: '个请求',
+  children: '子代理', session: '会话', models: '按模型', model: '模型',
+  records: '请求记录', expand: '全部展开', collapse: '全部收起', loading: '正在读取会话用量…',
+  empty: '本会话还没有请求记录', noChildren: '暂无子代理', noModels: '暂无模型用量',
+  scope: '本会话及所有子代理 · 历史日志累计',
+  note: '统计包含本会话与全部后代的独立请求、重试和压缩调用，不重复计算继承历史。首 token 与速度仅使用已记录的时间信息，缺失时显示 —。',
+  failedLoad: '用量读取失败，已保留上次结果。', retry: '重新读取', completed: '已完成', running: '进行中', failed: '失败', interrupted: '已中断',
+  main: '主会话', turn: '轮', step: '步', started: '开始', duration: '耗时', firstDetail: '首 token',
+  provider: '供应商', status: '状态', exact: '完整 token 数',
+  answering: '正在回答...', firstWait: '首字耗时', sec: '秒', tokenWord: 'token', perSec: 'token/秒',
+  cacheShort: '缓存', avgCache: '平均缓存', avgRate: '平均速率', inProgress: '个进行中',
+}
+export type SessionUsageKey = keyof typeof usageZh
+export const usageEn: Record<SessionUsageKey, string> = {
+  tab: 'Usage', requests: 'Requests', tokens: 'Total tokens', hit: 'Cache hit rate', first: 'Avg. first token', speed: 'Token speed',
+  input: 'In', output: 'Out', read: 'Read', write: 'Write',
+  requestsCount: 'Requests', inputFull: 'Input', outputFull: 'Output', readFull: 'Cache read', writeFull: 'Cache write',
+  cacheHit: 'cache hits', compaction: 'Compaction', reqTimes: 'requests',
+  children: 'Subagents', session: 'Session', models: 'By model', model: 'Model',
+  records: 'Request log', expand: 'Expand all', collapse: 'Collapse all', loading: 'Reading session usage…',
+  empty: 'No requests in this session yet', noChildren: 'No subagents yet', noModels: 'No model usage yet',
+  scope: 'This session and all subagents · Historical log totals',
+  note: 'Includes independent requests, retries and compaction calls from this session and all descendants, without counting inherited history twice. Timing uses recorded timestamps only; missing values appear as —.',
+  failedLoad: 'Could not read usage. The last successful result is preserved.', retry: 'Retry', completed: 'Completed', running: 'Running', failed: 'Failed', interrupted: 'Interrupted',
+  main: 'Main session', turn: 'Turn', step: 'Step', started: 'Started', duration: 'Duration', firstDetail: 'First token',
+  provider: 'Provider', status: 'Status', exact: 'Exact token count',
+  answering: 'answering...', firstWait: 'first token', sec: 's', tokenWord: 'token', perSec: 'token/s',
+  cacheShort: 'cache', avgCache: 'avg cache', avgRate: 'avg rate', inProgress: 'in progress',
+}
+export const usageZhTW: Record<SessionUsageKey, string> = {
+  ...usageZh,
+  tab: '用量', requests: '請求數', tokens: '總 tokens', hit: '命中率', first: '平均首 token', speed: 'token 速度',
+  input: '入', output: '出', read: '讀', write: '寫',
+  requestsCount: '請求數量', inputFull: '輸入', outputFull: '輸出', readFull: '快取讀取', writeFull: '快取寫入',
+  cacheHit: '快取命中', compaction: '壓縮呼叫', reqTimes: '個請求',
+  children: '子代理', session: '會話', models: '按模型', records: '請求記錄', expand: '全部展開', collapse: '全部收起',
+  loading: '正在讀取會話用量…', empty: '本會話還沒有請求記錄', noChildren: '暫無子代理', noModels: '暫無模型用量',
+  scope: '本會話及所有子代理 · 歷史日誌累計',
+  note: '統計包含本會話與全部後代的獨立請求、重試和壓縮呼叫，不重複計算繼承歷史。首 token 與速度僅使用已記錄的時間資訊，缺失時顯示 —。',
+  failedLoad: '用量讀取失敗，已保留上次結果。', retry: '重新讀取', completed: '已完成', running: '進行中', failed: '失敗', interrupted: '已中斷',
+  main: '主會話', turn: '輪', step: '步', started: '開始', duration: '耗時', firstDetail: '首 token', provider: '供應商', status: '狀態', exact: '完整 token 數',
+  answering: '正在回答...', firstWait: '首字耗時', sec: '秒', tokenWord: 'token', perSec: 'token/秒',
+  cacheShort: '快取', avgCache: '平均快取', avgRate: '平均速率', inProgress: '個進行中',
+}

package/src/client/use-session-detail.ts

@@ -0,0 +1,50 @@
+/** Serialized polling for one visible Usage view, never leaking another
+ * session's answer. Abort and stop all timers when the tab unmounts. */
+import { useEffect, useRef, useState } from 'react'
+import type { SessionUsageDetail } from '../wire.ts'
+import { fetchSessionDetail } from './api.ts'
+
+export const DETAIL_POLL_MS = 1_500
+
+export function useSessionDetail(sessionId: string): {
+  detail: SessionUsageDetail | null
+  loading: boolean
+  error: boolean
+  retry: () => void
+} {
+  const [reading, setReading] = useState<{ sessionId: string; detail: SessionUsageDetail | null; error: boolean } | null>(null)
+  const refresh = useRef<(() => void) | null>(null)
+  useEffect(() => {
+    let active = true
+    let pending = false
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let controller: AbortController | undefined
+    const request = (): void => {
+      if (!active || pending || !sessionId) return
+      if (timer !== undefined) clearTimeout(timer)
+      pending = true
+      controller = new AbortController()
+      void fetchSessionDetail(sessionId, controller.signal).then(detail => {
+        if (active) setReading({ sessionId, detail, error: false })
+      }).catch(() => {
+        if (active) setReading(previous => ({ sessionId, detail: previous?.sessionId === sessionId ? previous.detail : null, error: true }))
+      }).finally(() => {
+        pending = false
+        if (active) timer = setTimeout(request, DETAIL_POLL_MS)
+      })
+    }
+    const wake = (): void => { if (document.visibilityState === 'visible') request() }
+    refresh.current = request
+    document.addEventListener('visibilitychange', wake)
+    request()
+    return () => {
+      active = false
+      refresh.current = null
+      controller?.abort()
+      if (timer !== undefined) clearTimeout(timer)
+      document.removeEventListener('visibilitychange', wake)
+    }
+  }, [sessionId])
+  const current = reading?.sessionId === sessionId ? reading : null
+  return { detail: current?.detail ?? null, loading: current === null, error: current?.error ?? false, retry: () => refresh.current?.() }
+}

package/src/query.ts

@@ -104,6 +104,9 @@ export function aggregateSamples(
   const from = filter.from
   const to = filter.to
   const buckets = bucketsInRange(from, to, granularity)
+  // Materialize once: the qualified-name pre-pass below and the main fold
+  // both walk the samples, and a generator input may only be consumed once.
+  const all = [...samples]
   const out: TokenTotalRange = {
     from,
     to,
@@ -151,7 +154,11 @@ export function aggregateSamples(
   const bucketCacheHit = new Map<string, number>()
   const bucketCacheMiss = new Map<string, number>()
 
-  for (const sample of samples) {
+  // One model, one row: every qualified routing name folds onto its bare
+  // model key before the first aggregation (see aliasQualifiedModels).
+  const modelAlias = aliasQualifiedModels(new Set(all.map((sample) => modelKeyOf(sample))))
+
+  for (const sample of all) {
     const bucket = bucketOf(sample, from, to, granularity)
     if (bucket === null) continue
     if (sample.turn) {
@@ -192,7 +199,8 @@ export function aggregateSamples(
     out.cacheMiss += missSide
     const modelRef = sample.model && sample.model !== '' ? sample.model : '(unknown)'
     const provider = providerOf(modelRef)
-    const model = normalizeModelName(sample.modelName?.trim() || modelNameOf(modelRef))
+    const modelBase = modelKeyOf(sample)
+    const model = modelAlias.get(modelBase) ?? modelBase
     const sources = modelProviders.get(model) ?? new Set<string>()
     sources.add(provider)
     modelProviders.set(model, sources)
@@ -272,6 +280,49 @@ export function aggregateSamples(
   return out
 }
 
+/** The aggregation key of one sample: the resolved display name when the
+ *  host resolved one, else the bare model ref — normalized like every
+ *  display name so the key is stable across routes and refreshes. */
+function modelKeyOf(sample: UsageSample): string {
+  const modelRef = sample.model && sample.model !== '' ? sample.model : '(unknown)'
+  return normalizeModelName(sample.modelName?.trim() || modelNameOf(modelRef))
+}
+
+/**
+ * Qualified-name aliases: "workbuddy-ai-plugin/deepseek-v4.1-flash" and
+ * "deepseek-v4.1-flash" are the same model reached through a routing
+ * namespace, so a name containing "/" merges onto the LONGEST suffix after a
+ * "/" that is itself a model key in this dataset (chains like a/b/c → b/c → c
+ * resolve transitively). The merge is dataset-relative on purpose: a slash
+ * that names no bare model in the data ("GPT/6.1 sol" beside "gpt-6.1-sol")
+ * is a genuinely different name and stays its own row — see the
+ * distinct-slashes case in tests/model-aggregation.test.mjs.
+ */
+function aliasQualifiedModels(names: Set<string>): Map<string, string> {
+  const alias = new Map<string, string>()
+  for (const name of names) {
+    if (!name.includes('/')) continue
+    const parts = name.split('/')
+    for (let i = 1; i < parts.length; i++) {
+      const suffix = parts.slice(i).join('/')
+      if (names.has(suffix)) {
+        alias.set(name, suffix)
+        break
+      }
+    }
+  }
+  for (const name of [...alias.keys()]) {
+    let target = alias.get(name)!
+    const seen = new Set([name])
+    while (alias.has(target) && !seen.has(target)) {
+      seen.add(target)
+      target = alias.get(target)!
+    }
+    alias.set(name, target)
+  }
+  return alias
+}
+
 function modelsSorted(
   totals: Map<string, number>,
   cache: Map<string, { hit: number; miss: number }>,

package/src/routes.ts

@@ -18,7 +18,8 @@ import type { UsageStore, UsageDayRow, UsageHourRow } from './store.ts'
 import type { UsageCollector } from './collector.ts'
 import { aggregateSamples } from './query.ts'
 import type { Granularity, UsageSample } from './query.ts'
-import type { BackfillStatus, SessionUsageRequest, TokenTotalRange, TokenTotalRequest } from './wire.ts'
+import type { BackfillStatus, SessionUsageDetail, SessionUsageRequest, TokenTotalRange, TokenTotalRequest } from './wire.ts'
+import { buildSessionUsageDetail } from './session-detail.ts'
 import { UsageError, readJsonBody, writeError, writeJson } from './wire.ts'
 import type { SessionUsageService } from './session-usage.ts'
 import { createTrustFence, type TrustFence, type TrustInputs } from './trust-fence.ts'
@@ -228,6 +229,14 @@ export function buildUsageRoute(ctx: Context, deps: RoutesDeps): UsageWebRoute {
         writeJson(res, { ok: true, value })
         return
       }
+      if (method === 'POST' && path === '/token-total/api/session-detail') {
+        const body = (await readJsonBody(req)) as Partial<SessionUsageRequest>
+        const sessionId = typeof body.sessionId === 'string' ? body.sessionId.trim() : ''
+        if (sessionId === '' || sessionId.length > 200) throw new UsageError(400, 'token total: session needs a valid sessionId')
+        const value = await buildSessionUsageDetail(deps.persistence(), deps.sessions(), sessionId, ctx)
+        writeJson(res, { ok: true, value })
+        return
+      }
       if (method === 'POST' && path === '/token-total/api/status') {
         writeJson(res, { ok: true, value: deps.collector.status })
         return
@@ -260,4 +269,4 @@ export function buildUsageRoute(ctx: Context, deps: RoutesDeps): UsageWebRoute {
   return { kind: 'prefix', path: '/token-total/api', handler }
 }
 
-export type { BackfillStatus, TokenTotalRange, TokenTotalRequest, SessionUsageRequest }
+export type { BackfillStatus, TokenTotalRange, TokenTotalRequest, SessionUsageRequest, SessionUsageDetail }

package/src/session-detail.ts

@@ -0,0 +1,182 @@
+import type {
+  Context,
+  UsageSessionEvent,
+  UsageSessionHandle,
+  UsageSessionHeader,
+  UsageSessionPersistence,
+  UsageSessionSnapshot,
+  UsageSessionStore,
+} from './context-types.ts'
+import { UsageFold } from './collector.ts'
+import { resolveModelNames, resolveProviderNames } from './model-names.ts'
+import type { SessionUsageDetail, SessionUsageTotals } from './wire.ts'
+
+const zero = (): SessionUsageTotals => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 })
+function add(a: SessionUsageTotals, b: SessionUsageTotals): void {
+  a.uncachedInputTokens += b.uncachedInputTokens; a.outputTokens += b.outputTokens
+  a.cacheReadTokens += b.cacheReadTokens; a.cacheWriteTokens += b.cacheWriteTokens
+}
+function usageOf(x: any): SessionUsageTotals {
+  const u = x?.usage ?? x
+  return { uncachedInputTokens: Number(u?.inputTokens) || 0, outputTokens: Number(u?.outputTokens) || 0, cacheReadTokens: Number(u?.cacheReadTokens) || 0, cacheWriteTokens: Number(u?.cacheWriteTokens) || 0 }
+}
+function positive(u: SessionUsageTotals): boolean { return u.uncachedInputTokens + u.outputTokens + u.cacheReadTokens + u.cacheWriteTokens > 0 }
+function routeOf(x: any): { provider: string; model: string } {
+  const source = x?.message?.source ?? x?.source ?? x?.request ?? x?.context ?? x
+  return { provider: typeof source?.provider === 'string' ? source.provider : '', model: typeof source?.model === 'string' ? source.model : '' }
+}
+function streamUsage(data: any): { usage?: SessionUsageTotals; firstTime?: number } {
+  let firstTime: number | undefined
+  let usage: SessionUsageTotals | undefined
+  for (const r of Array.isArray(data?.stream) ? data.stream : []) {
+    const t = typeof r?.time === 'number' ? r.time : undefined
+    if (firstTime === undefined && t !== undefined && (r?.type === 'chunk' || r?.chunk?.type === 'text' || r?.chunk?.type === 'content')) firstTime = t
+    if (r?.type === 'chunk' && r?.chunk?.type === 'usage') usage = usageOf(r.chunk)
+  }
+  return { usage, firstTime }
+}
+function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
+  const x: any = item
+  if (x?.header?.id && typeof x.header.id === 'string') return x.header
+  return typeof x?.id === 'string' && x.id ? x : null
+}
+async function read(p: UsageSessionPersistence, id: string, live?: UsageSessionHandle): Promise<{ events: readonly UsageSessionEvent[]; cut: number }> {
+  if (live?.snapshotEvents && typeof live.inheritedEventCount === 'number') return { events: live.snapshotEvents(), cut: Math.max(0, live.inheritedEventCount) }
+  if (p.open) {
+    const h = await p.open(id, 'read'); const out: UsageSessionEvent[] = []
+    try { for (let off = 0;;) { const page = await h.read(off, 500); if (!page.events.length) break; out.push(...page.events); off += page.events.length } }
+    finally { await h.close().catch(() => {}) }
+    return { events: out, cut: Math.max(0, Number(h.inheritedEventCount) || 0) }
+  }
+  if (p.inspect) { const x = await p.inspect(id); return { events: x.events, cut: Math.max(0, Number(x.inheritedEventCount) || 0) } }
+  throw new Error('no readable persistence seam (need open or inspect)')
+}
+
+type MutableRecord = SessionUsageDetail['records'][number] & { _attempt: number; _lastUsage: SessionUsageTotals }
+function nameOf(h: UsageSessionHeader | undefined, id: string): string {
+  const x: any = h
+  if (typeof x?.name === 'string' && x.name) return x.name
+  if (typeof x?.title === 'string' && x.title) return x.title
+  if (typeof x?.cwd === 'string' && x.cwd) return x.cwd.split(/[\\/]/).filter(Boolean).pop() || id
+  return id
+}
+
+async function one(p: UsageSessionPersistence, id: string, header: UsageSessionHeader | undefined, live: UsageSessionHandle | undefined) {
+  const { events, cut } = await read(p, id, live)
+  const fold = new UsageFold(); const totals = zero(); const records: MutableRecord[] = []
+  const byKey = new Map<string, MutableRecord>(); let route = live?.requestContext?.() ?? {}
+  let ordinal = 0
+  // Per-turn display names come from the first real user prompt of each turn
+  // (other `user/message` kinds are runtime context / skill catalog injections);
+  // the prompt usually lands before `turn/start`, so buffer it until the turn opens.
+  let currentTurn = 0; let effort = ''; let pendingTopic = ''
+  const turnTopics = new Map<number, string>()
+  const own = events.filter(e => !(cut > 0 && typeof e.seq === 'number' && e.seq < cut))
+  // Real session names: a subagent carries its delegation label on its
+  // `subagent/descriptor` event ("完成日志明细后端"), every session can carry a
+  // generated `session/title`; only fall back to the header/cwd/id guesses.
+  let label = '', title = ''
+  for (const ev of own) {
+    const d: any = ev.data ?? {}
+    if (!label && ev.type === 'subagent/descriptor' && typeof d.label === 'string' && d.label.trim()) label = d.label.trim()
+    if (!title && ev.type === 'session/title' && typeof d.title === 'string' && d.title.trim()) title = d.title.trim()
+    if (label && title) break
+  }
+  const name = label || title || nameOf(header, id)
+  for (const ev of own) {
+    const d: any = ev.data ?? {}; const turn = Number.isFinite(d.turn) ? d.turn : 0; const step = Number.isFinite(d.step) ? d.step : 0
+    if (ev.type === 'request/context') { route = { ...route, ...routeOf(d) }; continue }
+    const r = routeOf(d); if (r.provider || r.model) route = { ...route, ...r }
+    if (ev.type === 'turn/start') {
+      currentTurn = turn
+      if (pendingTopic && !turnTopics.has(currentTurn)) { turnTopics.set(currentTurn, pendingTopic); pendingTopic = '' }
+    } else if (ev.type === 'user/message' && d.source?.kind === 'user') {
+      const block = (Array.isArray(d.content) ? d.content : []).find((b: any) => b?.type === 'text' && typeof b.text === 'string')
+      const text = String(block?.text ?? '').replace(/\s+/g, ' ').trim()
+      if (text) {
+        if (currentTurn > 0 && !turnTopics.has(currentTurn)) turnTopics.set(currentTurn, text)
+        else pendingTopic = text
+      }
+    } else if (ev.type === 'request/header') {
+      const e = d.header?.config?.reasoningEffort
+      if (typeof e === 'string' && e) {
+        effort = e
+        for (const x of records) if (x.status === 'running') x.effort = e
+      }
+    }
+    let rec: MutableRecord | undefined
+    if (ev.type === 'step/start' || ev.type === 'llm/retry-started') {
+      const key = `${turn}:${step}`
+      if (ev.type === 'llm/retry-started' || !byKey.has(key)) {
+        const previous = byKey.get(key)
+        if (previous && ev.type === 'llm/retry-started' && previous.status === 'running') { previous.status = 'failed'; previous.finishedAt = ev.time }
+        rec = { id: `${id}:${turn}:${step}:${ordinal++}`, sessionId: id, sessionName: name, turn, step, startedAt: ev.time, finishedAt: null, provider: r.provider || route.provider || '', model: r.model || route.model || '', status: 'running', totals: zero(), firstTokenMs: null, tokensPerSecond: null, turnName: '', effort, _attempt: ev.type === 'llm/retry-started' ? 1 : 0, _lastUsage: zero() }
+        records.push(rec); byKey.set(key, rec)
+      }
+    } else if (ev.type === 'assistant/chunk' || ev.type === 'assistant/message' || ev.type === 'assistant/attempt') {
+      rec = byKey.get(`${turn}:${step}`)
+      if (!rec) { rec = { id: `${id}:${turn}:${step}:${ordinal++}`, sessionId: id, sessionName: name, turn, step, startedAt: ev.time, finishedAt: null, provider: r.provider || route.provider || '', model: r.model || route.model || '', status: 'running', totals: zero(), firstTokenMs: null, tokensPerSecond: null, turnName: '', effort, _attempt: 0, _lastUsage: zero() }; records.push(rec); byKey.set(`${turn}:${step}`, rec) }
+      if (r.provider) rec.provider = r.provider; if (r.model) rec.model = r.model
+      const su = streamUsage(d); const u = ev.type === 'assistant/message' ? (d.usage ? usageOf(d) : su.usage) : ev.type === 'assistant/chunk' ? (d.chunk?.type === 'usage' ? usageOf(d.chunk) : undefined) : (d.usage ? usageOf(d) : su.usage)
+      if (u) {
+        rec._lastUsage = u; rec.totals = u
+        if (positive(u) && rec.firstTokenMs === null) {
+          const rawFirst = su.firstTime ?? (typeof d.chunk?.time === 'number' ? d.chunk.time : ev.time)
+          rec.firstTokenMs = Math.max(0, rawFirst - rec.startedAt)
+        }
+      }
+      if (ev.type !== 'assistant/chunk') { rec.finishedAt = ev.time; rec.status = ev.type === 'assistant/attempt' ? 'failed' : 'completed' }
+      const elapsedMs = rec.finishedAt === null ? null : Math.max(0, rec.finishedAt - rec.startedAt)
+      if (elapsedMs !== null && elapsedMs > 0 && rec.totals.outputTokens > 0) rec.tokensPerSecond = rec.totals.outputTokens / (elapsedMs / 1000)
+    } else if (ev.type === 'turn/end') {
+      const recs = records.filter(x => x.turn === turn && x.status === 'running'); for (const x of recs) { x.status = 'interrupted'; x.finishedAt = ev.time }
+    } else if (ev.type === 'compaction/summary') {
+      const u = usageOf(d); rec = { id: `${id}:compaction:${ordinal++}`, sessionId: id, sessionName: name, turn: 0, step: 0, startedAt: ev.time, finishedAt: ev.time, provider: typeof d.provider === 'string' ? d.provider : '', model: typeof d.model === 'string' ? d.model : '', status: 'completed', totals: u, firstTokenMs: null, tokensPerSecond: null, turnName: '', effort: '', _attempt: 0, _lastUsage: u }; records.push(rec)
+    }
+    const sample = fold.fold(ev); if (sample && !sample.turn) add(totals, { uncachedInputTokens: sample.inputTokens, outputTokens: sample.outputTokens, cacheReadTokens: sample.cacheReadTokens, cacheWriteTokens: sample.cacheWriteTokens })
+  }
+  // Records intentionally expose the final fold value; fold corrections can make
+  // a stream sample disappear, so reconcile aggregate totals from the records only
+  // for presentation while `totals` remains the authoritative UsageFold result.
+  const requests = records.length
+  const firsts = records.map(x => x.firstTokenMs).filter((x): x is number => x !== null)
+  const outputSeconds = records.reduce((n, x) => n + x.totals.outputTokens, 0)
+  const elapsed = records.reduce((n, x) => n + (x.firstTokenMs ?? 0), 0)
+  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: elapsed > 0 ? outputSeconds / (elapsed / 1000) : null }
+}
+
+export async function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail> {
+  const raw = await persistence.list(typeof persistence.open === 'function' ? undefined : undefined)
+  const headers = raw.map(headerOf).filter((x): x is UsageSessionHeader => x !== null)
+  const live = new Map((sessions?.list() ?? []).map(x => [x.id, x])); const children = new Map<string, string[]>()
+  for (const h of headers) if (h.parentSession) children.set(h.parentSession, [...(children.get(h.parentSession) ?? []), h.id])
+  for (const h of live.values()) { const p = h.header?.parentSession ?? h.parentSession; if (p) children.set(p, [...(children.get(p) ?? []).filter(x => x !== h.id), h.id]) }
+  const ids: string[] = []; const seen = new Set([rootId]); const q = [rootId]
+  while (q.length) for (const c of children.get(q.shift()!) ?? []) if (!seen.has(c)) { seen.add(c); ids.push(c); q.push(c) }
+  const all = [rootId, ...ids]; const parts = await Promise.all(all.map(id => one(persistence, id, headers.find(h => h.id === id), live.get(id))))
+  const root = parts[0]; const totals = zero(); const models = new Map<string, { totals: SessionUsageTotals; requests: number; providers: Set<string> }>(); const records = parts.flatMap(x => x.records); for (const p of parts) add(totals, p.totals)
+  for (const r of records) { const key = r.model || '(unknown)'; const m = models.get(key) ?? { totals: zero(), requests: 0, providers: new Set<string>() }; add(m.totals, r.totals); m.requests++; if (r.provider) m.providers.add(r.provider); models.set(key, m) }
+  const subagents = parts.slice(1).map(p => ({ sessionId: p.id, name: p.name, totals: p.totals, requests: p.requests, averageFirstTokenMs: p.averageFirstTokenMs, tokensPerSecond: p.tokensPerSecond }))
+  const routeMap = new Map<string, SessionUsageDetail['routes'][number]>()
+  for (const r of records) if (r.provider || r.model) { const id = `${r.provider}/${r.model}`; routeMap.set(id, { id, provider: r.provider, name: r.provider, model: r.model, status: r.status === 'running' ? 'running' : r.status === 'failed' ? 'failed' : 'completed' }) }
+  const llm: any = ctx?.get?.('llm'); for (const x of llm?.listProviders?.() ?? []) if (x?.id && !routeMap.has(x.id)) routeMap.set(x.id, { id: x.id, provider: x.id, name: x.name || x.id, model: '', status: 'idle' })
+  // Model rows key on the raw historical model id; attach the model selector's
+  // display name plus the serving providers so the by-model card never shows a
+  // route id as the model name and can disambiguate same-named models.
+  const providerNames = resolveProviderNames(llm)
+  const refOf = (provider: string, model: string): string => provider ? `${provider}/${model}` : model
+  const refs: string[] = []
+  for (const [model, m] of models) if (model !== '(unknown)') {
+    if (m.providers.size) for (const provider of m.providers) refs.push(refOf(provider, model))
+    else refs.push(refOf('', model))
+  }
+  const names = await resolveModelNames(refs, llm)
+  const displayNameOf = (model: string, providers: Set<string>): string | undefined => {
+    // One row can span providers; take the first display name they agree on.
+    const keys = providers.size ? [...providers].map(provider => refOf(provider, model)) : [refOf('', model)]
+    for (const key of keys) { const resolved = names.get(key)?.trim(); if (resolved) return resolved }
+    return undefined
+  }
+  return { sessionId: rootId, totals, requests: parts.reduce((n, p) => n + p.requests, 0), averageFirstTokenMs: root.averageFirstTokenMs, tokensPerSecond: root.tokensPerSecond, 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()] }
+}

package/src/wire.ts

@@ -136,6 +136,62 @@ export interface SessionUsageRequest {
   sessionId: string
 }
 
+/** Detailed per-session usage view used by the Usage tab. */
+export interface SessionUsageDetail {
+  sessionId: string
+  totals: SessionUsageTotals
+  requests: number
+  averageFirstTokenMs: number | null
+  tokensPerSecond: number | null
+  subagents: Array<{
+    sessionId: string
+    name: string
+    totals: SessionUsageTotals
+    requests: number
+    averageFirstTokenMs: number | null
+    tokensPerSecond: number | null
+  }>
+  models: Array<{
+    /** Raw model id from the historical route. Stays the row key and the
+     *  fallback label (also the tooltip) when no display name is resolved. */
+    model: string
+    /** The model selector's display name for this model, resolved host-side
+     *  from the llm service metadata. Optional so an older host (or an
+     *  unresolvable route) still serves a valid payload. */
+    name?: string
+    /** Display names (raw ids when unknown) of every provider that served this
+     *  model in the session, first-seen order. The by-model card shows these in
+     *  gray when two rows end up sharing one display name. */
+    providers?: string[]
+    totals: SessionUsageTotals
+    requests: number
+  }>
+  records: Array<{
+    id: string
+    sessionId: string
+    sessionName: string
+    turn: number
+    step: number
+    startedAt: number
+    finishedAt: number | null
+    provider: string
+    model: string
+    status: 'running' | 'completed' | 'failed' | 'interrupted'
+    totals: SessionUsageTotals
+    firstTokenMs: number | null
+    tokensPerSecond: number | null
+    turnName: string
+    effort: string
+  }>
+  routes: Array<{
+    id: string
+    provider: string
+    name: string
+    model: string
+    status: 'idle' | 'running' | 'completed' | 'failed'
+  }>
+}
+
 /** The backfill (historical session scan) progress state. */
 export interface BackfillStatus {
   running: boolean