dsh-token-total 1.0.6 → 1.0.8

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

@@ -10,13 +10,17 @@ export function useSessionDetail(sessionId: string): {
   detail: SessionUsageDetail | null
   loading: boolean
   error: boolean
-  retry: () => void
+  /** Manual refresh: runs now when idle, or right after an in-flight poll lands. */
+  refresh: () => void
+  /** Wall-clock time of the last successful read, for the "as of" stamp. */
+  updatedAt: number | null
 } {
-  const [reading, setReading] = useState<{ sessionId: string; detail: SessionUsageDetail | null; error: boolean } | null>(null)
+  const [reading, setReading] = useState<{ sessionId: string; detail: SessionUsageDetail | null; error: boolean; updatedAt: number | null } | null>(null)
   const refresh = useRef<(() => void) | null>(null)
   useEffect(() => {
     let active = true
     let pending = false
+    let wantedNow = false
     let timer: ReturnType<typeof setTimeout> | undefined
     let controller: AbortController | undefined
     const request = (): void => {
@@ -25,16 +29,21 @@ export function useSessionDetail(sessionId: string): {
       pending = true
       controller = new AbortController()
       void fetchSessionDetail(sessionId, controller.signal).then(detail => {
-        if (active) setReading({ sessionId, detail, error: false })
+        if (active) setReading({ sessionId, detail, error: false, updatedAt: Date.now() })
       }).catch(() => {
-        if (active) setReading(previous => ({ sessionId, detail: previous?.sessionId === sessionId ? previous.detail : null, error: true }))
+        if (active) setReading(previous => ({ sessionId, detail: previous?.sessionId === sessionId ? previous.detail : null, error: true, updatedAt: previous?.sessionId === sessionId ? previous.updatedAt : null }))
       }).finally(() => {
         pending = false
-        if (active) timer = setTimeout(request, DETAIL_POLL_MS)
+        // A refresh pressed mid-poll skips the regular interval and refetches
+        // as soon as the in-flight answer lands, so the click never stalls.
+        if (active) timer = setTimeout(request, wantedNow ? 0 : DETAIL_POLL_MS)
+        wantedNow = false
       })
     }
     const wake = (): void => { if (document.visibilityState === 'visible') request() }
-    refresh.current = request
+    // Manual refresh: fire immediately when idle; when a poll is already in
+    // flight, mark it and refetch right after it settles.
+    refresh.current = () => { if (pending) wantedNow = true; else request() }
     document.addEventListener('visibilitychange', wake)
     request()
     return () => {
@@ -46,5 +55,5 @@ export function useSessionDetail(sessionId: string): {
     }
   }, [sessionId])
   const current = reading?.sessionId === sessionId ? reading : null
-  return { detail: current?.detail ?? null, loading: current === null, error: current?.error ?? false, retry: () => refresh.current?.() }
+  return { detail: current?.detail ?? null, loading: current === null, error: current?.error ?? false, refresh: () => refresh.current?.(), updatedAt: current?.updatedAt ?? null }
 }

package/src/model-names.ts

@@ -7,6 +7,10 @@ import { modelNameOf, providerOf } from './shared.ts'
 const LOOKUP_CONCURRENCY = 4
 const LOOKUP_TIMEOUT_MS = 2000
 
+/** Raised when a lookup's own timer fires — i.e. the shared phase budget is
+ *  spent. Workers stop on this instead of trusting the wall clock again. */
+class LookupTimeoutError extends Error {}
+
 /** Bound metadata queries even if an adapter fails to honor cancellation. */
 async function lookup<T>(read: (signal: AbortSignal) => Promise<T>, timeoutMs: number): Promise<T> {
   const controller = new AbortController()
@@ -17,7 +21,7 @@ async function lookup<T>(read: (signal: AbortSignal) => Promise<T>, timeoutMs: n
       new Promise<never>((_, reject) => {
         timer = setTimeout(() => {
           controller.abort()
-          reject(new Error('model display-name lookup timed out'))
+          reject(new LookupTimeoutError('model display-name lookup timed out'))
         }, timeoutMs)
       }),
     ])
@@ -81,8 +85,12 @@ export async function resolveModelNames(
         try {
           const info = await lookup((signal) => llm.resolveModelInfo!(providerOf(ref), modelNameOf(ref), signal), remaining)
           if (info.name?.trim()) names.set(ref, info.name)
-        } catch {
+        } catch (error) {
           // Metadata is auxiliary: never lose usage because a route is gone.
+          // The shared budget is spent once our own timer fires; stop instead
+          // of trusting the clock again (setTimeout vs Date.now can disagree
+          // by ~1ms and would otherwise queue extra lookups past the deadline).
+          if (error instanceof LookupTimeoutError) break
         }
       }
     }))
@@ -105,8 +113,10 @@ export async function resolveModelNames(
             const name = byId.get(modelNameOf(ref))
             if (name?.trim()) names.set(ref, name)
           }
-        } catch {
-          // A dormant provider must not prevent historical totals from loading.
+        } catch (error) {
+          // A dormant provider must not prevent historical totals from loading;
+          // a fired timer still ends the whole catalog phase (see above).
+          if (error instanceof LookupTimeoutError) break
         }
       }
     }))

package/src/session-detail.ts

@@ -9,6 +9,7 @@ import type {
 } from './context-types.ts'
 import { UsageFold } from './collector.ts'
 import { resolveModelNames, resolveProviderNames } from './model-names.ts'
+import { decodeRateOf } from './shared.ts'
 import type { SessionUsageDetail, SessionUsageTotals } from './wire.ts'
 
 const zero = (): SessionUsageTotals => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 })
@@ -20,20 +21,65 @@ 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
+/** Whether one stream chunk carries the model's first output token. Mirrors
+ *  `isTokenDelta` in @deepseek-ai/dsh-llm so the decode window starts on the
+ *  same chunk the official `sessionStats` projection starts it on. */
+function isTokenDelta(chunk: any): boolean {
+  switch (chunk?.type) {
+    case 'text-delta': case 'reasoning-delta': return chunk.text !== ''
+    case 'tool-call-delta': return chunk.argumentsDelta !== '' || chunk.name !== undefined
+    default: return false
+  }
+}
+/** Reconstructed time of the first token in one packed delta run (mirrors
+ *  `runFirstTokenTime`): a name-bearing tool-call run starts at its first
+ *  member, every other run at its first non-empty fragment. */
+function runFirstTokenTime(run: any): number | undefined {
+  if (run?.type === 'tool-call-chunks' && run.name !== undefined) return run.time0
+  const fragments = run?.type === 'tool-call-chunks' ? run.args : run?.texts
+  if (!Array.isArray(fragments)) return undefined
+  let time = Number(run.time0)
+  for (let i = 0; i < fragments.length; i++) {
+    if (i > 0) time += Number(run.dt?.[i - 1]) || 0
+    if (fragments[i] !== '') return time
+  }
+  return undefined
+}
+/** Time of the first token in one compact attempt stream (mirrors
+ *  `assistantStreamFirstTokenTime`). */
+function streamFirstTokenTime(stream: any): number | undefined {
+  for (const r of Array.isArray(stream) ? stream : []) {
+    const t = r?.type === 'chunk' ? (isTokenDelta(r.chunk) ? r.time : undefined) : runFirstTokenTime(r)
+    if (typeof t === 'number' && Number.isFinite(t)) return t
+  }
+  return undefined
+}
+/** Time of the first token carried by one live `assistant/chunk` payload. */
+function chunkFirstTokenTime(data: any, fallback: number): number | undefined {
+  const c = data?.chunk
+  if (!c) return undefined
+  const timed = c.chunk && typeof c.time === 'number' ? c : null
+  if (!isTokenDelta(timed ? timed.chunk : c)) return undefined
+  return timed ? timed.time : typeof c.time === 'number' ? c.time : fallback
+}
+function streamUsage(data: any): { usage?: SessionUsageTotals; raw?: any } {
   let usage: SessionUsageTotals | undefined
+  let raw: any
   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)
+    if (r?.type === 'chunk' && r?.chunk?.type === 'usage') { usage = usageOf(r.chunk); raw = r.chunk.usage ?? r.chunk }
   }
-  return { usage, firstTime }
+  return { usage, raw }
+}
+/** Provider-reported completion tokens, or null when unreported or invalid:
+ *  an invalid count must not enter the decode quotient (mirrors
+ *  `usageOutputTokens` in the sessionStats projection). */
+function usageOutputTokens(x: any): number | null {
+  const value = (x?.usage ?? x)?.outputTokens
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null
 }
 function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSessionHeader | null {
   const x: any = item
@@ -83,6 +129,12 @@ async function one(p: UsageSessionPersistence, id: string, header: UsageSessionH
     if (label && title) break
   }
   const name = label || title || nameOf(header, id)
+  // Decode accounting mirrors the official `sessionStats` projection: a step
+  // records its first token once (the earliest attempt wins, surviving an
+  // in-step retry), and only the assembled `assistant/message` closes the
+  // decode window, so failed attempts and cancelled steps stay uncounted.
+  const stepTokens = new Map<string, number>()
+  const closedSteps = new Set<string>()
   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 }
@@ -110,28 +162,41 @@ async function one(p: UsageSessionPersistence, id: string, header: UsageSessionH
       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() }
+        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, decodeMs: 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) }
+      const key = `${turn}:${step}`
+      rec = byKey.get(key)
+      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, decodeMs: null, tokensPerSecond: null, turnName: '', effort, _attempt: 0, _lastUsage: zero() }; records.push(rec); byKey.set(key, 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 (u) { rec._lastUsage = u; rec.totals = u }
+      // The first token opens both this row's first-token wait and the step's
+      // decode window; the earliest attempt keeps it across an in-step retry.
+      const tokenAt = streamFirstTokenTime(d.stream) ?? chunkFirstTokenTime(d, ev.time)
+      if (tokenAt !== undefined) {
+        if (!stepTokens.has(key)) stepTokens.set(key, tokenAt)
+        if (rec.firstTokenMs === null) rec.firstTokenMs = Math.max(0, tokenAt - rec.startedAt)
+      }
+      if (ev.type !== 'assistant/chunk') {
+        rec.finishedAt = ev.time; rec.status = ev.type === 'assistant/attempt' ? 'failed' : 'completed'
+        // Only an assembled message closes the decode window, and only its own
+        // top-level `usage` counts, exactly as the official sessionStats
+        // projection counts it: a failed attempt, a cancelled step or a
+        // stream-only usage sample contributes no decode time, so the card, the
+        // turn summaries and the composer bottom bar all quote one speed.
+        const stepFirst = stepTokens.get(key)
+        if (rec.status === 'completed' && !closedSteps.has(key) && stepFirst !== undefined && usageOutputTokens(d.usage) !== null) {
+          closedSteps.add(key)
+          rec.decodeMs = Math.max(0, rec.finishedAt - stepFirst)
+          if (rec.decodeMs > 0 && rec.totals.outputTokens > 0) rec.tokensPerSecond = rec.totals.outputTokens / (rec.decodeMs / 1000)
         }
       }
-      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 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, decodeMs: 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 })
   }
@@ -139,11 +204,11 @@ async function one(p: UsageSessionPersistence, id: string, header: UsageSessionH
   // 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)
+  // The first-token average quotes answered requests only: a failed attempt or
+  // 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: elapsed > 0 ? outputSeconds / (elapsed / 1000) : null }
+  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) }
 }
 
 export async function buildSessionUsageDetail(persistence: UsageSessionPersistence, sessions: UsageSessionStore | undefined, rootId: string, ctx?: Context): Promise<SessionUsageDetail> {
@@ -155,7 +220,7 @@ export async function buildSessionUsageDetail(persistence: UsageSessionPersisten
   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)
+  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]>()
@@ -178,5 +243,8 @@ export async function buildSessionUsageDetail(persistence: UsageSessionPersisten
     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()] }
+  // 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()] }
 }

package/src/shared.ts

@@ -53,6 +53,29 @@ export function modelNameOf(modelRef: string): string {
   return modelRef
 }
 
+/** The decode accounting one request row must expose: the wall window from the
+ *  step's first token to its assembled assistant message, plus the output tokens
+ *  that window produced. */
+export interface DecodeRowLike {
+  decodeMs: number | null
+  totals: { outputTokens: number }
+}
+
+/** Decode throughput across rows: Σ(output tokens) / Σ(decode window), matching
+ *  the `sessionStats` projection's decodeTokens/decodeMs rate that the composer
+ *  bottom bar shows. Rows without a decode window (failed attempts, cancelled
+ *  steps, running requests) are excluded, so the card, the turn summaries and
+ *  the bottom bar all report one speed. */
+export function decodeRateOf(rows: readonly DecodeRowLike[]): number | null {
+  let ms = 0
+  let tokens = 0
+  // typeof, not `!== null`: a bundle newer than the payload it is handed (a
+  // cached detail, an older server) leaves `decodeMs` absent, and one absent
+  // field must not turn the whole sum into NaN.
+  for (const row of rows) if (typeof row.decodeMs === 'number' && Number.isFinite(row.decodeMs)) { ms += row.decodeMs; tokens += row.totals.outputTokens }
+  return ms > 0 ? tokens / (ms / 1000) : null
+}
+
 /** Canonicalize a DISPLAY NAME, never a route id. Case and word separators
  *  do not distinguish models, but versions, punctuation and suffixes do:
  *  gpt-6.1-sol / GPT 6.1 sol -> gpt-6.1-sol, not gpt-6.1 or gpt-61-sol.

package/src/wire.ts

@@ -179,6 +179,11 @@ export interface SessionUsageDetail {
     status: 'running' | 'completed' | 'failed' | 'interrupted'
     totals: SessionUsageTotals
     firstTokenMs: number | null
+    /** Wall window from this step's first token to the assembled assistant
+     *  message — the same decode window the `sessionStats` projection counts
+     *  (decodeMs). Null when the request never assembled a message or reported
+     *  no usage, so it stays out of every throughput quotient. */
+    decodeMs: number | null
     tokensPerSecond: number | null
     turnName: string
     effort: string