dsh-token-total 1.0.0 → 1.0.2

package/src/store.ts

@@ -34,6 +34,11 @@ export interface UsageCounters {
   cacheReadTokens: number
   cacheWriteTokens: number
   requests: number // usage events (API calls) in the bucket
+  /** Provider calls in the bucket that FAILED (error / cancelled before any
+   *  content): a subset of `requests`, never larger than it. Rows persisted
+   *  before the counter existed may lack it; the schema normalizes that to 0
+   *  and every subsequent fold writes the number back. */
+  failures: number
   turns: number // completed turns attributed to this model in the bucket
   lastSeen: number // epoch ms of the newest sample
 }
@@ -57,6 +62,10 @@ export const usageDayRowSchema = z.object({
   cacheReadTokens: z.number(),
   cacheWriteTokens: z.number(),
   requests: z.number(),
+  // Optional: rows persisted before the failure counter existed must stay
+  // readable (the domain format has no migration path, and bumping its
+  // version would reject every existing store). A missing value folds as 0.
+  failures: z.number().default(0),
   turns: z.number(),
   lastSeen: z.number(),
 })
@@ -70,6 +79,7 @@ export const usageHourRowSchema = z.object({
   cacheReadTokens: z.number(),
   cacheWriteTokens: z.number(),
   requests: z.number(),
+  failures: z.number().default(0),
   turns: z.number(),
   lastSeen: z.number(),
 })
@@ -101,12 +111,21 @@ export const usageHistoryDomain = defineDomain({
       hoursBackfilledSessions: z.array(z.string()).optional(),
       hoursLiveFirstSeq: z.record(z.string(), z.number()).optional(),
       hoursReady: z.boolean().optional(),
+      // The FAILURE counter arrived after both token cursors were populated,
+      // so it needs its own pair too: replaying through the day/hour cursors
+      // to recover historic failures would re-add every token. This pass only
+      // writes the failed-call counts.
+      failuresBackfilledSessions: z.array(z.string()).optional(),
+      failuresLiveFirstSeq: z.record(z.string(), z.number()).optional(),
+      failuresReady: z.boolean().optional(),
     }),
     initial: {
       backfilledSessions: [] as string[],
       liveFirstSeq: {},
       hoursBackfilledSessions: [] as string[],
       hoursLiveFirstSeq: {},
+      failuresBackfilledSessions: [] as string[],
+      failuresLiveFirstSeq: {},
     },
   },
   // Two tables, one domain version: storage-domain builds an empty map for a
@@ -137,6 +156,9 @@ interface UsageCursor {
   hoursBackfilledSessions?: string[]
   hoursLiveFirstSeq?: Record<string, number>
   hoursReady?: boolean
+  failuresBackfilledSessions?: string[]
+  failuresLiveFirstSeq?: Record<string, number>
+  failuresReady?: boolean
 }
 
 export class UsageStore {
@@ -375,6 +397,93 @@ export class UsageStore {
     return write
   }
 
+  /** Session ids already replayed into the FAILURE counter (third cursor
+   *  pair, same reason as the hour pair: the day and hour cursors were
+   *  already full when the counter arrived). */
+  async failuresSeenSessions(): Promise<Set<string>> {
+    await this.ready
+    return new Set(this.cursor()?.failuresBackfilledSessions ?? [])
+  }
+
+  /** Per-session seq of the first LIVE-observed event, failure-counter share. */
+  async failuresLiveSequences(): Promise<Map<string, number>> {
+    await this.ready
+    return new Map(Object.entries(this.cursor()?.failuresLiveFirstSeq ?? {}))
+  }
+
+  /** Persist failure-pass replay progress (merges; serialized on the same
+   *  chain as every other cursor write). */
+  async markFailuresSeenSessions(ids: Iterable<string>): Promise<void> {
+    const write = this.markChain.then(async () => {
+      await this.ready
+      const value = this.requireCursor()
+      const seen = new Set(value.failuresBackfilledSessions ?? [])
+      for (const id of ids) seen.add(id)
+      await this.domainHandle?.global?.set({
+        ...value,
+        backfilledSessions: value.backfilledSessions ?? [],
+        failuresBackfilledSessions: [...seen],
+      })
+    })
+    this.markChain = write.then(
+      () => undefined,
+      () => undefined,
+    )
+    return write
+  }
+
+  /** Record the failure-pass live boundary per session (earliest wins). */
+  async markFailuresLiveSequences(entries: Iterable<readonly [string, number]>): Promise<void> {
+    const write = this.markChain.then(async () => {
+      await this.ready
+      const value = this.requireCursor()
+      const merged: Record<string, number> = { ...(value.failuresLiveFirstSeq ?? {}) }
+      let changed = false
+      for (const [id, seq] of entries) {
+        const prev = merged[id]
+        if (prev === undefined || seq < prev) {
+          merged[id] = seq
+          changed = true
+        }
+      }
+      if (!changed) return
+      await this.domainHandle?.global?.set({
+        ...value,
+        backfilledSessions: value.backfilledSessions ?? [],
+        failuresLiveFirstSeq: merged,
+      })
+    })
+    this.markChain = write.then(
+      () => undefined,
+      () => undefined,
+    )
+    return write
+  }
+
+  /** Whether the failure counter covers every replayable session. */
+  async failuresReady(): Promise<boolean> {
+    await this.ready
+    return this.cursor()?.failuresReady === true
+  }
+
+  /** Mark the failure history complete; the upgrade pass then never reruns. */
+  async markFailuresReady(): Promise<void> {
+    const write = this.markChain.then(async () => {
+      await this.ready
+      const value = this.requireCursor()
+      await this.domainHandle?.global?.set({
+        ...value,
+        backfilledSessions: value.backfilledSessions ?? [],
+        failuresReady: true,
+      })
+    })
+    this.markChain = write.then(
+      () => undefined,
+      () => undefined,
+    )
+    return write
+  }
+
   /** Drop every row and the whole cursor, re-bounding each named session at
    *  its WIPE-TIME WATERMARK (the store-rebuild escape hatch for corrupted
    *  history or attribution-logic upgrades).
@@ -415,6 +524,12 @@ export class UsageStore {
         hoursBackfilledSessions: [],
         hoursLiveFirstSeq: { ...liveFirstSeq },
         hoursReady: false,
+        // The failure pass resets with the others (this object replaces the
+        // global wholesale): its cursor must start empty and its boundary
+        // must equal the day boundary for the same reason.
+        failuresBackfilledSessions: [],
+        failuresLiveFirstSeq: { ...liveFirstSeq },
+        failuresReady: false,
       })
       for (const key of [...table.keys()]) await table.delete(key)
       for (const key of [...hourTable.keys()]) await hourTable.delete(key)
@@ -490,6 +605,23 @@ export class UsageStore {
     )
   }
 
+  /** Fold ONLY the failure count of a sample into the day and hour rows. The
+   *  failure upgrade pass uses this: its replay walks logs the token passes
+   *  already consumed, so the tokens and the request marker must not be added
+   *  a second time — only the failed-call counter may move. */
+  async recordFailure(sample: UsageSample): Promise<void> {
+    await this.record({
+      day: sample.day,
+      hour: sample.hour,
+      model: sample.model,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+      failed: true,
+    })
+  }
+
   /** The row identity a sample lands on: turn markers use the synthetic
    *  (turns) model, unlabelled calls the (unknown) one. */
   private targetsOf(sample: UsageSample): { provider: string; model: string } {
@@ -578,6 +710,7 @@ function emptyCounters(provider: string, model: string): UsageCounters {
     cacheReadTokens: 0,
     cacheWriteTokens: 0,
     requests: 0,
+    failures: 0,
     turns: 0,
     lastSeen: Date.now(),
   }
@@ -597,6 +730,9 @@ function accumulate<T extends UsageCounters>(base: T, sample: UsageSample): T {
   return {
     ...base,
     requests: base.requests + (sample.request ? 1 : 0),
+    // `failures` is missing on rows persisted before the counter existed;
+    // fold it as 0 and write the number back so the pass converges to it.
+    failures: (base.failures ?? 0) + (sample.failed ? 1 : 0),
     inputTokens: base.inputTokens + sample.inputTokens,
     outputTokens: base.outputTokens + sample.outputTokens,
     cacheReadTokens: base.cacheReadTokens + sample.cacheReadTokens,

package/src/wire.ts

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