dsh-token-total 1.0.0 → 1.0.2

package/src/context-types.ts

@@ -150,6 +150,16 @@ export interface UsageSessionPersistence {
 export interface UsageLlmService {
   resolveModelInfo?(provider: string, model: string, signal?: AbortSignal): Promise<{ name: string }>
   listModels?(provider: string): Promise<readonly { 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
@@ -168,8 +178,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/src/index.ts

@@ -212,6 +212,34 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
     await collector.backfillHours(ctx.sessionPersistence, ctx.sessions, controller.signal)
   }
 
+  // The failure counter arrived after BOTH token cursors were populated, so
+  // an existing store needs one more replay to recover historic failures.
+  // Same shape as the hour upgrade: only after the hour pass settled cleanly
+  // (a fresh install's passes already folded failures and set the flag, so
+  // this returns immediately), and with a live boundary for open sessions.
+  const ensureFailureHistory = async (): Promise<void> => {
+    await store.readyPromise()
+    if (await store.failuresReady()) return
+    if (!(await store.hasAnyDayRows())) return
+    if (collector.status.error !== undefined) return
+    const previous = await store.failuresLiveSequences()
+    const boundaries = new Map<string, number>()
+    for (const handle of ctx.sessions.list()) {
+      const seq = handle.seq
+      if (typeof seq === 'number' && Number.isFinite(seq) && seq >= 0) {
+        boundaries.set(handle.id, seq)
+        continue
+      }
+      const old = previous.get(handle.id)
+      boundaries.set(handle.id, typeof old === 'number' ? old : -1)
+    }
+    await store.markFailuresLiveSequences(boundaries)
+    scanController?.abort()
+    const controller = new AbortController()
+    scanController = controller
+    await collector.backfillFailures(ctx.sessionPersistence, ctx.sessions, controller.signal)
+  }
+
   ctx.effect(() => {
     collector.start()
     // Keep the per-session tree cache honest: every committed event of any
@@ -226,6 +254,7 @@ export function apply(ctx: Context, config: TokenTotalConfig = {}): void {
     void (async () => {
       await rescan()
       await ensureHourHistory()
+      await ensureFailureHistory()
     })()
     return () => {
       scanController?.abort()

package/src/model-names.ts

@@ -26,6 +26,40 @@ async function lookup<T>(read: (signal: AbortSignal) => Promise<T>, timeoutMs: n
   }
 }
 
+/** 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 function resolveProviderNames(llm?: UsageLlmService): Record<string, string> {
+  const names: Record<string, string> = Object.create(null)
+  if (!llm) return names
+  try {
+    for (const provider of catalog(llm.listProviders?.())) {
+      const name = provider.name?.trim()
+      if (provider.id && name) names[provider.id] = name
+    }
+  } catch {
+    // Metadata is auxiliary: a broken catalog must never fail the range query.
+  }
+  try {
+    for (const entry of catalog(llm.listConfigurableProviders?.())) {
+      const name = entry.displayName?.trim()
+      if (entry.provider && name && names[entry.provider] === undefined) names[entry.provider] = name
+    }
+  } catch {
+    // Same contract as above.
+  }
+  return names
+}
+
+/** Both catalogs are declared synchronous, but a host that publishes them over
+ *  a remote face would hand back a promise; treat anything that is not an array
+ *  as "no metadata" instead of throwing mid-query. */
+function catalog<T>(value: readonly T[] | undefined): readonly T[] {
+  return Array.isArray(value) ? value : []
+}
+
 /** Resolve each distinct route once per range query. Unknown/deleted providers
  *  fall back to their bare historical model names in aggregateSamples(). */
 export async function resolveModelNames(

package/src/query.ts

@@ -51,6 +51,14 @@ export interface UsageSample {
   cacheWriteTokens: number
   turn?: boolean // true for a completed-turn marker
   request?: boolean // true when this sample also counts one provider call
+  /** 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 {
@@ -105,6 +113,7 @@ export function aggregateSamples(
     outputTokens: 0,
     cacheTokens: 0,
     requests: 0,
+    failures: 0,
     turns: 0,
     cacheHit: 0,
     cacheMiss: 0,
@@ -123,6 +132,12 @@ export function aggregateSamples(
   // tracked alongside the token volume.
   const modelCache = new Map<string, { hit: number; miss: number }>()
   const providerCache = new Map<string, { hit: number; miss: number }>()
+  // Cross-dimension splits: the two ranked lists render as side-by-side cards
+  // whose rows explain themselves on hover (which providers served this model,
+  // which models this provider served), so both directions are tracked here
+  // in the same pass rather than by re-walking the samples per row.
+  const modelProviderTotals = new Map<string, Map<string, number>>()
+  const providerModelTotals = new Map<string, Map<string, number>>()
   const active = new Set<string>()
   // Per-bucket accumulation (the reasonix dayTotals): the stacked trend chart
   // reads the bucket's byModel / byProvider, so every token-bearing sample
@@ -131,6 +146,7 @@ export function aggregateSamples(
   const bucketByProvider = new Map<string, Map<string, number>>()
   const bucketTotals = new Map<string, number>()
   const bucketRequests = new Map<string, number>()
+  const bucketFailures = new Map<string, number>()
   const bucketTurns = new Map<string, number>()
   const bucketCacheHit = new Map<string, number>()
   const bucketCacheMiss = new Map<string, number>()
@@ -147,18 +163,22 @@ export function aggregateSamples(
     // provider billed for this call — uncached input, output, cache reads
     // and writes. The hit/miss rate denominators below stay input-side only.
     const total = sample.inputTokens + sample.outputTokens + sample.cacheReadTokens + sample.cacheWriteTokens
+    // UsageFold emits signed bucket corrections. Even a net-zero correction
+    // can move prompt tokens between cache hit and miss, so only all-zero
+    // buckets are a marker with no token accounting.
+    const hasTokenDelta = sample.inputTokens !== 0 || sample.outputTokens !== 0
+      || sample.cacheReadTokens !== 0 || sample.cacheWriteTokens !== 0
+    if (sample.failed) {
+      out.failures++
+      bucketFailures.set(bucket, (bucketFailures.get(bucket) ?? 0) + 1)
+    }
     if (sample.request) {
-      // One provider call, whether or not it produced tokens — reasonix counts
-      // failed calls too. A marker with no buckets is a request and nothing
-      // else: it must not create a model row, mark its day active, or open an
-      // empty daily bucket. A marker that DOES carry buckets
-      // (`compaction/summary` states the call and its usage in one sample) is
-      // counted here and again through the token accounting below — the two
-      // count different things, so neither doubles the other.
       out.requests++
       bucketRequests.set(bucket, (bucketRequests.get(bucket) ?? 0) + 1)
-      if (total <= 0) continue
     }
+    // Pure markers must not create a model row or an active day. A marker
+    // carrying a correction still updates every billing/cache bucket below.
+    if (!hasTokenDelta) continue
     out.tokens += total
     out.inputTokens += sample.inputTokens
     out.outputTokens += sample.outputTokens
@@ -178,6 +198,18 @@ export function aggregateSamples(
     modelProviders.set(model, sources)
     modelTotals.set(model, (modelTotals.get(model) ?? 0) + total)
     providerTotals.set(provider, (providerTotals.get(provider) ?? 0) + total)
+    let modelSplitMap = modelProviderTotals.get(model)
+    if (!modelSplitMap) {
+      modelSplitMap = new Map()
+      modelProviderTotals.set(model, modelSplitMap)
+    }
+    modelSplitMap.set(provider, (modelSplitMap.get(provider) ?? 0) + total)
+    let providerSplitMap = providerModelTotals.get(provider)
+    if (!providerSplitMap) {
+      providerSplitMap = new Map()
+      providerModelTotals.set(provider, providerSplitMap)
+    }
+    providerSplitMap.set(model, (providerSplitMap.get(model) ?? 0) + total)
     const mc = modelCache.get(model) ?? { hit: 0, miss: 0 }
     mc.hit += sample.cacheReadTokens
     mc.miss += missSide
@@ -222,14 +254,15 @@ export function aggregateSamples(
       byModel: byModelObj,
       byProvider: byProviderObj,
       requests: bucketRequests.get(bucket) ?? 0,
+      failures: bucketFailures.get(bucket) ?? 0,
       turns: bucketTurns.get(bucket) ?? 0,
       cacheHit: bucketCacheHit.get(bucket) ?? 0,
       cacheMiss: bucketCacheMiss.get(bucket) ?? 0,
     })
   }
 
-  out.models = modelsSorted(modelTotals, modelCache, modelProviders)
-  out.providers = providersSorted(providerTotals, providerCache)
+  out.models = modelsSorted(modelTotals, modelCache, modelProviders, modelProviderTotals)
+  out.providers = providersSorted(providerTotals, providerCache, providerModelTotals)
   out.topModel = out.models[0]?.model ?? ''
   out.topProvider = out.providers[0]?.provider ?? ''
   if (out.tokens > 0) {
@@ -243,23 +276,61 @@ function modelsSorted(
   totals: Map<string, number>,
   cache: Map<string, { hit: number; miss: number }>,
   sources: Map<string, Set<string>>,
+  splits: Map<string, Map<string, number>>,
 ): ModelTokenUsage[] {
   const out: ModelTokenUsage[] = []
   for (const [model, tokens] of totals) {
     const c = cache.get(model)
     const providers = [...(sources.get(model) ?? [])].sort()
-    out.push({ model, provider: providers.length === 1 ? providers[0]! : '', providers, tokens, percent: 0, cacheHit: c?.hit ?? 0, cacheMiss: c?.miss ?? 0 })
+    out.push({
+      model,
+      provider: providers.length === 1 ? providers[0]! : '',
+      providers,
+      providerTokens: providerSplit(splits.get(model)),
+      tokens,
+      percent: 0,
+      cacheHit: c?.hit ?? 0,
+      cacheMiss: c?.miss ?? 0,
+    })
   }
   out.sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model))
   return out
 }
 
-function providersSorted(totals: Map<string, number>, cache: Map<string, { hit: number; miss: number }>): ProviderTokenUsage[] {
+function providersSorted(
+  totals: Map<string, number>,
+  cache: Map<string, { hit: number; miss: number }>,
+  splits: Map<string, Map<string, number>>,
+): ProviderTokenUsage[] {
   const out: ProviderTokenUsage[] = []
   for (const [provider, tokens] of totals) {
     const c = cache.get(provider)
-    out.push({ provider, tokens, percent: 0, cacheHit: c?.hit ?? 0, cacheMiss: c?.miss ?? 0 })
+    out.push({
+      provider,
+      tokens,
+      percent: 0,
+      cacheHit: c?.hit ?? 0,
+      cacheMiss: c?.miss ?? 0,
+      modelTokens: modelSplit(splits.get(provider)),
+    })
   }
   out.sort((a, b) => b.tokens - a.tokens)
   return out
 }
+
+/** One model's per-provider split, largest first (ties by id for a stable
+ *  order across refreshes). Empty when the response carries no cross data. */
+function providerSplit(split: Map<string, number> | undefined): Array<{ provider: string; tokens: number }> {
+  if (split === undefined) return []
+  return [...split]
+    .map(([provider, tokens]) => ({ provider, tokens }))
+    .sort((a, b) => b.tokens - a.tokens || a.provider.localeCompare(b.provider))
+}
+
+/** One provider's per-model split, largest first (ties by name). */
+function modelSplit(split: Map<string, number> | undefined): Array<{ model: string; tokens: number }> {
+  if (split === undefined) return []
+  return [...split]
+    .map(([model, tokens]) => ({ model, tokens }))
+    .sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model))
+}

package/src/routes.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Context, UsageLlmService } from './context-types.ts'
-import { resolveModelNames } from './model-names.ts'
+import { resolveModelNames, resolveProviderNames } from './model-names.ts'
 import type { UsageHttpRequest, UsageHttpResponse, UsageWebRoute } from './context-types.ts'
 import type { UsageStore, UsageDayRow, UsageHourRow } from './store.ts'
 import type { UsageCollector } from './collector.ts'
@@ -162,12 +162,30 @@ export async function aggregateRange(
       for (let i = 0; i < row.requests; i++) {
         yield { day, hour, model: row.model, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, request: true }
       }
+      // Failed calls ride the row as a count too. They are folded as their own
+      // marker (never as an extra request): the call's request is already
+      // counted above, and a zero-token failure must not open a model row.
+      for (let i = 0; i < (row.failures ?? 0); i++) {
+        yield { day, hour, model: row.model, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, failed: true }
+      }
       for (let i = 0; i < row.turns; i++) {
         yield { day, hour, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, turn: true }
       }
     }
   })()
-  return aggregateSamples(samples, { from, to }, granularity)
+  const stats = aggregateSamples(samples, { from, to }, granularity)
+  // Provider labels ride along with the aggregate: the ranked provider card
+  // shows the selector's display name, and the hover detail names the models
+  // underneath it. Only providers actually present in the range are included,
+  // so the payload stays proportional to the ranking it decorates.
+  const resolved = resolveProviderNames(llm)
+  const providerNames: Record<string, string> = Object.create(null)
+  for (const provider of stats.providers) {
+    const label = resolved[provider.provider]
+    if (label !== undefined) providerNames[provider.provider] = label
+  }
+  if (Object.keys(providerNames).length > 0) stats.providerNames = providerNames
+  return stats
 }
 
 /** Build the single fenced prefix route serving the /token-total/api JSON RPC.

package/src/session-usage.ts

@@ -25,6 +25,7 @@
 
 import type {
   UsageSessionEvent,
+  UsageSessionHandle,
   UsageSessionHeader,
   UsageSessionPersistence,
   UsageSessionSnapshot,
@@ -68,6 +69,10 @@ function headerOf(item: UsageSessionHeader | UsageSessionSnapshot): UsageSession
   return typeof row?.id === 'string' && row.id !== '' ? row : null
 }
 
+function inheritedCount(cut: unknown): number {
+  return typeof cut === 'number' && Number.isSafeInteger(cut) && cut >= 0 ? cut : 0
+}
+
 /** Read one stored session's events through whichever persistence seam the
  *  host line exposes (alpha open/read/close wins; rc.1 inspect is the tail). */
 async function readEvents(
@@ -78,13 +83,12 @@ async function readEvents(
   if (typeof persistence.open === 'function') {
     const handle = await persistence.open(id, 'read', signal === undefined ? undefined : { signal })
     try {
-      const cut = handle.inheritedEventCount
-      const inheritedCut = typeof cut === 'number' && Number.isSafeInteger(cut) && cut >= 0 ? cut : 0
+      const inheritedCut = inheritedCount(handle.inheritedEventCount)
       const collected: UsageSessionEvent[] = []
       let offset = 0
       const PAGE = 500
       for (;;) {
-        if (signal?.aborted) break
+        signal?.throwIfAborted()
         const slice = await handle.read(offset, PAGE, signal === undefined ? undefined : { signal })
         const page = ((slice && slice.events) ? slice.events : []) as readonly UsageSessionEvent[]
         if (page.length === 0) break
@@ -98,7 +102,7 @@ async function readEvents(
   }
   if (typeof persistence.inspect === 'function') {
     const inspection = await persistence.inspect(id, signal)
-    return { events: inspection.events, inheritedCut: inspection.inheritedEventCount ?? 0 }
+    return { events: inspection.events, inheritedCut: inheritedCount(inspection.inheritedEventCount) }
   }
   throw new Error('no readable persistence seam (need open or inspect)')
 }
@@ -108,49 +112,59 @@ async function sumOneSession(
   persistence: UsageSessionPersistence,
   id: string,
   signal?: AbortSignal,
-): Promise<SessionUsageTotals> {
-  const { events, inheritedCut } = await readEvents(persistence, id, signal)
+  live?: UsageSessionHandle,
+): Promise<{ totals: SessionUsageTotals; compaction: SessionUsageTotals }> {
+  signal?.throwIfAborted()
+  const { events, inheritedCut } = typeof live?.snapshotEvents === 'function'
+    && typeof live.inheritedEventCount === 'number'
+    ? { events: live.snapshotEvents(), inheritedCut: inheritedCount(live.inheritedEventCount) }
+    : await readEvents(persistence, id, signal)
   const fold = new UsageFold()
   const totals: SessionUsageTotals = { ...ZERO }
+  const compaction: SessionUsageTotals = { ...ZERO }
   for (const ev of events) {
     if (inheritedCut > 0 && typeof ev.seq === 'number' && ev.seq < inheritedCut) continue
     const sample = fold.fold(ev)
     if (sample === null || sample.turn) continue
-    totals.uncachedInputTokens += sample.inputTokens
-    totals.outputTokens += sample.outputTokens
-    totals.cacheReadTokens += sample.cacheReadTokens
-    totals.cacheWriteTokens += sample.cacheWriteTokens
+    const buckets: SessionUsageTotals = {
+      uncachedInputTokens: sample.inputTokens,
+      outputTokens: sample.outputTokens,
+      cacheReadTokens: sample.cacheReadTokens,
+      cacheWriteTokens: sample.cacheWriteTokens,
+    }
+    add(totals, buckets)
+    if (ev.type === 'compaction/summary') add(compaction, buckets)
   }
-  return totals
+  return { totals, compaction }
 }
 
 export 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. */
-  private cache = new Map<string, { at: number; value: SessionUsageTree; members: Set<string> }>()
-
-  /** 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 {
-    for (const [rootId, entry] of this.cache) {
-      if (entry.members.has(sessionId)) this.cache.delete(rootId)
-    }
+  /** Short-lived tree reads; any live event can invalidate tree membership. */
+  private cache = new Map<string, { at: number; value: SessionUsageTree }>()
+  /** Any event can introduce a new descendant while an async read is running. */
+  private generation = 0
+
+  /** 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 {
+    this.generation++
+    this.cache.clear()
   }
 
   /** 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. */
   async tree(
     persistence: UsageSessionPersistence,
     sessions: UsageSessionStore | undefined,
     rootId: string,
     signal?: AbortSignal,
   ): Promise<SessionUsageTree> {
+    signal?.throwIfAborted()
     const hit = this.cache.get(rootId)
     if (hit !== undefined && Date.now() - hit.at < CACHE_TTL_MS) return hit.value
+    const generation = this.generation
 
     const headers = await this.listHeaders(persistence, signal)
     const children = new Map<string, string[]>()
@@ -163,10 +177,10 @@ export class SessionUsageService {
     }
     // A brand-new live subagent may not be materialized in persistence yet;
     // the live store still knows its parent, so fold those in too.
-    for (const handle of sessions?.list() ?? []) {
-      const parent = (handle as { parentSession?: string }).parentSession
+    const live = new Map((sessions?.list() ?? []).map((handle) => [handle.id, handle]))
+    for (const handle of live.values()) {
+      const parent = handle.header?.parentSession ?? handle.parentSession
       if (typeof parent !== 'string' || parent === '' || parent === handle.id) continue
-      if (headers.some((h) => h.id === handle.id)) continue
       const bucket = children.get(parent)
       if (bucket === undefined) children.set(parent, [handle.id])
       else if (!bucket.includes(handle.id)) bucket.push(handle.id)
@@ -185,23 +199,21 @@ export class SessionUsageService {
       }
     }
 
-    const self = await sumOneSession(persistence, rootId, signal).catch(() => ({ ...ZERO }))
+    const root = await sumOneSession(persistence, rootId, signal, live.get(rootId))
+    const self = root.totals
     const subagents: SessionUsageTotals = { ...ZERO }
     for (const id of descendants) {
-      const one = await sumOneSession(persistence, id, signal).catch(() => ({ ...ZERO }))
-      add(subagents, one)
+      const one = await sumOneSession(persistence, id, signal, live.get(id))
+      add(subagents, one.totals)
     }
     const total: SessionUsageTotals = { ...self }
     add(total, subagents)
-    const value: SessionUsageTree = { self, subagents, total, subagentSessions: descendants.length }
+    const value: SessionUsageTree = { self, selfCompaction: root.compaction, subagents, total, subagentSessions: descendants.length }
 
-    if (signal?.aborted !== true) {
+    signal?.throwIfAborted()
+    if (generation === this.generation) {
       if (this.cache.size >= CACHE_MAX) this.cache.clear()
-      this.cache.set(rootId, {
-        at: Date.now(),
-        value,
-        members: new Set([rootId, ...descendants]),
-      })
+      this.cache.set(rootId, { at: Date.now(), value })
     }
     return value
   }