@brimveyn/aimux 1.22.12 → 1.23.0

package/src/services/usage-history/cost.ts

@@ -0,0 +1,149 @@
+import type { UsageDay, UsageDays, UsageTokens } from './store'
+
+/**
+ * Notional cost of the recorded tokens.
+ *
+ * Nothing here is a charge. Claude Code and Codex run on subscriptions, not
+ * metered API billing, so these numbers answer one question only: what would
+ * this usage have cost at API list price. Every surface that renders them says
+ * "estimated" for that reason.
+ */
+
+export interface ModelRate {
+  /** USD per million input tokens. */
+  input: number
+  /** USD per million output tokens. */
+  output: number
+}
+
+const MILLION = 1_000_000
+
+/**
+ * List prices, matched by id prefix so dated snapshots
+ * (`claude-sonnet-4-5-20250929`) hit the same row as the alias. Longest prefix
+ * wins, so `claude-opus-4-6` is not shadowed by a shorter `claude-opus` entry —
+ * there deliberately isn't one. A model whose price is not published here is
+ * left out of the total rather than guessed at.
+ */
+const RATES: [prefix: string, rate: ModelRate][] = [
+  ['claude-fable-5', { input: 10, output: 50 }],
+  ['claude-mythos-5', { input: 10, output: 50 }],
+  ['claude-opus-5', { input: 5, output: 25 }],
+  ['claude-opus-4-8', { input: 5, output: 25 }],
+  ['claude-opus-4-7', { input: 5, output: 25 }],
+  ['claude-opus-4-6', { input: 5, output: 25 }],
+  ['claude-sonnet-5', { input: 3, output: 15 }],
+  ['claude-sonnet-4-6', { input: 3, output: 15 }],
+  ['claude-haiku-4-5', { input: 1, output: 5 }],
+]
+
+/** Cache reads bill at a tenth of the input rate; writes at 1.25x (the 5-minute TTL). */
+const CACHE_READ_MULTIPLIER = 0.1
+const CACHE_WRITE_MULTIPLIER = 1.25
+
+export function rateFor(model: string): ModelRate | null {
+  let best: ModelRate | null = null
+  let bestLength = 0
+  for (const [prefix, rate] of RATES) {
+    if (model.startsWith(prefix) && prefix.length > bestLength) {
+      best = rate
+      bestLength = prefix.length
+    }
+  }
+  return best
+}
+
+export function costOf(tokens: UsageTokens, rate: ModelRate): number {
+  return (
+    (tokens.input * rate.input +
+      tokens.output * rate.output +
+      tokens.cacheRead * rate.input * CACHE_READ_MULTIPLIER +
+      tokens.cacheWrite * rate.input * CACHE_WRITE_MULTIPLIER) /
+    MILLION
+  )
+}
+
+/** What the cache reads would have cost at the full input rate, minus what they did cost. */
+export function savedByCache(tokens: UsageTokens, rate: ModelRate): number {
+  return (tokens.cacheRead * rate.input * (1 - CACHE_READ_MULTIPLIER)) / MILLION
+}
+
+function scale(tokens: UsageTokens, factor: number): UsageTokens {
+  return {
+    cacheRead: tokens.cacheRead * factor,
+    cacheWrite: tokens.cacheWrite * factor,
+    input: tokens.input * factor,
+    output: tokens.output * factor,
+    total: tokens.total * factor,
+  }
+}
+
+export interface CostBreakdown {
+  saved: number
+  total: number
+  /**
+   * Tokens `total` does not cover, so a page can say so instead of presenting a
+   * partial sum as the whole bill. Two ways in: a model with no published rate
+   * (every Codex model, today), and tokens no model claimed at all.
+   */
+  unpricedTokens: number
+}
+
+function emptyBreakdown(): CostBreakdown {
+  return { saved: 0, total: 0, unpricedTokens: 0 }
+}
+
+/**
+ * A day's cost, split across its models in proportion to their token share.
+ *
+ * ponytail: the store keeps one total per model, not an input/output/cache split
+ * per model, so a day's overall split is applied to each model's share. Exact
+ * whenever a day used one model — the common case — and off only when a day
+ * mixes tiers whose input/output ratios also differ. Storing `UsageTokens` per
+ * model would make it exact, at the cost of a wider file and another migration;
+ * do that if the estimate is ever visibly wrong.
+ */
+export function dayCost(day: UsageDay): CostBreakdown {
+  const result = emptyBreakdown()
+  const { total } = day.tokens
+  if (total <= 0) return result
+
+  let attributed = 0
+  for (const [model, modelTotal] of Object.entries(day.models)) {
+    attributed += modelTotal
+    const rate = rateFor(model)
+    if (rate === null) {
+      result.unpricedTokens += modelTotal
+      continue
+    }
+    const share = scale(day.tokens, modelTotal / total)
+    result.total += costOf(share, rate)
+    result.saved += savedByCache(share, rate)
+  }
+
+  // Tokens no model claimed: a Codex transcript whose `model` line never
+  // appeared, or a day whose attribution was pruned out from under its totals.
+  // Unpriced for the same reason a missing rate is — nothing here knows what
+  // they cost — and counting them is what keeps the loop above from silently
+  // dropping a day's tokens out of the accounting altogether.
+  result.unpricedTokens += Math.max(0, total - attributed)
+
+  return result
+}
+
+export function totalCost(days: UsageDays): CostBreakdown {
+  const result = emptyBreakdown()
+  for (const day of Object.values(days)) {
+    const cost = dayCost(day)
+    result.saved += cost.saved
+    result.total += cost.total
+    result.unpricedTokens += cost.unpricedTokens
+  }
+  return result
+}
+
+export function formatUsd(amount: number): string {
+  if (amount >= 1000) return `$${Math.round(amount).toLocaleString('en-US').replaceAll(',', ' ')}`
+  if (amount >= 10) return `$${amount.toFixed(0)}`
+  return `$${amount.toFixed(2)}`
+}

package/src/services/usage-history/insights.ts

@@ -0,0 +1,314 @@
+import {
+  HOURS_IN_DAY,
+  localDay,
+  type UsageDay,
+  type UsageDays,
+  type UsageMean,
+  type UsageSession,
+} from './store'
+
+/**
+ * Derivations over the stored days, for the Activity / Projects / Records pages.
+ *
+ * Separate from `stats.ts`, which shapes the heatmap grid: that file is calendar
+ * geometry, this one is arithmetic over what the days contain. Everything here is
+ * pure and takes `UsageDays`, so it is testable without touching disk.
+ *
+ * Days recorded before the v2 rollup carry the new fields as empty rather than
+ * zeroed. Every function below reports a `days` count alongside its result so a
+ * page can say "no data" instead of rendering an empty span as a measurement.
+ */
+
+const MINUTES_IN_DAY = 24 * 60
+const MS_PER_DAY = 86_400_000
+
+export function parseDayKey(key: string): Date {
+  const [year, month, day] = key.split('-').map(Number)
+  return new Date(year ?? 0, (month ?? 1) - 1, day ?? 1)
+}
+
+/** Whole days apart, via `Date.UTC` on the calendar parts — a DST span is not a whole number of 24h periods. */
+export function daysBetween(from: Date, to: Date): number {
+  const utcOf = (date: Date): number =>
+    Date.UTC(date.getFullYear(), date.getMonth(), date.getDate())
+  return Math.round((utcOf(to) - utcOf(from)) / MS_PER_DAY)
+}
+
+/**
+ * One value per calendar day for the `count` days ending today, oldest first —
+ * the series a daily bar chart draws. Unrecorded days are zero, not skipped:
+ * the x-axis is time, and time does not pause on a day off.
+ */
+export function lastDays(
+  days: UsageDays,
+  count: number,
+  today: Date,
+  of: (day: UsageDay) => number
+): number[] {
+  return Array.from({ length: count }, (_, index) => {
+    const date = new Date(today)
+    date.setDate(date.getDate() - (count - 1 - index))
+    const day = days[localDay(date)]
+    return day === undefined ? 0 : of(day)
+  })
+}
+
+function promptDayKeys(days: UsageDays): string[] {
+  return Object.entries(days)
+    .filter(([, day]) => day.prompts > 0)
+    .map(([key]) => key)
+    .sort()
+}
+
+// ─── Activity ────────────────────────────────────────────────────────────────
+
+export interface StreakInfo {
+  current: number
+  longest: number
+  /** Largest run of consecutive prompt-less days between two active ones. */
+  longestGapDays: number
+}
+
+/**
+ * A streak that ends yesterday is still current: the day is not over, and
+ * breaking it at midnight would report every morning as a reset.
+ */
+export function streaks(days: UsageDays, today: Date): StreakInfo {
+  const keys = promptDayKeys(days)
+  if (keys.length === 0) return { current: 0, longest: 0, longestGapDays: 0 }
+
+  let longest = 1
+  let longestGapDays = 0
+  let run = 1
+  for (let index = 1; index < keys.length; index++) {
+    const gap = daysBetween(parseDayKey(keys[index - 1] ?? ''), parseDayKey(keys[index] ?? ''))
+    if (gap === 1) {
+      run += 1
+      if (run > longest) longest = run
+    } else {
+      if (gap - 1 > longestGapDays) longestGapDays = gap - 1
+      run = 1
+    }
+  }
+
+  const last = parseDayKey(keys.at(-1) ?? '')
+  const sinceLast = daysBetween(last, today)
+  // Only a run that reaches today or yesterday is still going. `run` is the
+  // length of the final run because the loop never resets it after the last gap.
+  const current = sinceLast <= 1 ? run : 0
+
+  return { current, longest, longestGapDays }
+}
+
+/** 24 buckets of prompts, summed across every day. */
+export function hourTotals(days: UsageDays): number[] {
+  const totals = Array.from({ length: HOURS_IN_DAY }, () => 0)
+  for (const day of Object.values(days)) {
+    for (let hour = 0; hour < HOURS_IN_DAY; hour++) {
+      totals[hour] = (totals[hour] ?? 0) + (day.hours[hour] ?? 0)
+    }
+  }
+  return totals
+}
+
+/**
+ * 7 buckets of prompts, Sunday first — the order `buildHeatmap` draws its rows
+ * in, so the bars and the calendar on the same page mean the same thing by
+ * "the top row".
+ */
+export function weekdayTotals(days: UsageDays): number[] {
+  const totals = Array.from({ length: 7 }, () => 0)
+  for (const [key, day] of Object.entries(days)) {
+    if (day.prompts === 0) continue
+    const index = parseDayKey(key).getDay()
+    totals[index] = (totals[index] ?? 0) + day.prompts
+  }
+  return totals
+}
+
+export interface TypicalDay {
+  /** Days that contributed — 0 means the pages must not render the times. */
+  days: number
+  endMinutes: number
+  startMinutes: number
+}
+
+/**
+ * The average local clock time of the day's first and last prompt.
+ *
+ * Read off the session spans rather than the hour buckets: those place the edges
+ * of a day to the hour, and `09:00` where the truth is `09:12` reads as a
+ * rounded guess rather than a measurement.
+ */
+export function typicalDay(days: UsageDays): TypicalDay {
+  let startSum = 0
+  let endSum = 0
+  let counted = 0
+
+  for (const day of Object.values(days)) {
+    let first = Infinity
+    let last = -Infinity
+    for (const session of Object.values(day.sessions)) {
+      if (session.first < first) first = session.first
+      if (session.last > last) last = session.last
+    }
+    if (!Number.isFinite(first) || !Number.isFinite(last)) continue
+
+    const firstAt = new Date(first)
+    const lastAt = new Date(last)
+    startSum += firstAt.getHours() * 60 + firstAt.getMinutes()
+    endSum += lastAt.getHours() * 60 + lastAt.getMinutes()
+    counted += 1
+  }
+
+  if (counted === 0) return { days: 0, endMinutes: 0, startMinutes: 0 }
+  return {
+    days: counted,
+    endMinutes: Math.round(endSum / counted) % MINUTES_IN_DAY,
+    startMinutes: Math.round(startSum / counted) % MINUTES_IN_DAY,
+  }
+}
+
+// ─── Projects and sessions ───────────────────────────────────────────────────
+
+export interface Ranked {
+  entries: [string, number][]
+  total: number
+}
+
+export function projectTotals(days: UsageDays, limit = 6): Ranked {
+  const totals: Record<string, number> = {}
+  for (const day of Object.values(days)) {
+    for (const [path, count] of Object.entries(day.projects)) {
+      totals[path] = (totals[path] ?? 0) + count
+    }
+  }
+  const entries = Object.entries(totals).sort((left, right) => right[1] - left[1])
+  let total = 0
+  for (const [, value] of entries) total += value
+  return { entries: entries.slice(0, limit), total }
+}
+
+export interface SessionStats {
+  count: number
+  /** Day key of the longest session, for the Records page. */
+  longestDay: string
+  longestMs: number
+  medianMs: number
+  /** Days that carried any session, the denominator for sessions-per-day. */
+  days: number
+  /** Sessions holding exactly one prompt — they last ~0 and would otherwise look like a bug. */
+  singlePrompt: number
+}
+
+export function sessionStats(days: UsageDays): SessionStats {
+  const durations: number[] = []
+  let count = 0
+  let longestMs = 0
+  let longestDay = ''
+  let dayCount = 0
+  let singlePrompt = 0
+
+  for (const [key, day] of Object.entries(days)) {
+    const sessions: UsageSession[] = Object.values(day.sessions)
+    if (sessions.length === 0) continue
+    dayCount += 1
+    for (const session of sessions) {
+      count += 1
+      if (session.prompts <= 1) singlePrompt += 1
+      const duration = Math.max(0, session.last - session.first)
+      durations.push(duration)
+      if (duration > longestMs) {
+        longestMs = duration
+        longestDay = key
+      }
+    }
+  }
+
+  durations.sort((left, right) => left - right)
+  // Every session is kept, so this is a true median — unlike the averages
+  // elsewhere in this file, which are reconstructed from a running sum.
+  const medianMs = durations.length === 0 ? 0 : (durations[Math.floor(durations.length / 2)] ?? 0)
+
+  return { count, days: dayCount, longestDay, longestMs, medianMs, singlePrompt }
+}
+
+/**
+ * Upper bounds in minutes. The last bucket is everything above the final bound,
+ * so the array the histogram draws is one longer than this one.
+ */
+const SESSION_BOUNDS = [5, 15, 30, 60, 120] as const
+
+/** One label per bucket, for the bar rows the Projects page draws. */
+export const SESSION_BUCKETS = [
+  'under 5 min',
+  '5 to 15 min',
+  '15 to 30 min',
+  '30 to 60 min',
+  '1 to 2 hours',
+  'over 2 hours',
+] as const
+
+/**
+ * How many sessions fell in each length bucket.
+ *
+ * A median and a longest say where the middle and the edge are but not the
+ * shape, and the shape is the interesting part: a day of one long session and a
+ * day of twenty two-minute ones have the same total and nothing else in common.
+ */
+export function sessionLengths(days: UsageDays): number[] {
+  const buckets = Array.from({ length: SESSION_BUCKETS.length }, () => 0)
+  for (const day of Object.values(days)) {
+    for (const session of Object.values(day.sessions)) {
+      const minutes = Math.max(0, session.last - session.first) / 60_000
+      const found = SESSION_BOUNDS.findIndex((bound) => minutes < bound)
+      const index = found === -1 ? buckets.length - 1 : found
+      buckets[index] = (buckets[index] ?? 0) + 1
+    }
+  }
+  return buckets
+}
+
+// ─── Means ───────────────────────────────────────────────────────────────────
+
+export function totalMean(days: UsageDays, pick: (day: UsageDay) => UsageMean): UsageMean {
+  let count = 0
+  let max = 0
+  let sum = 0
+  for (const day of Object.values(days)) {
+    const mean = pick(day)
+    count += mean.count
+    sum += mean.sum
+    if (mean.max > max) max = mean.max
+  }
+  return { count, max, sum }
+}
+
+export function meanOf(mean: UsageMean): number {
+  return mean.count === 0 ? 0 : mean.sum / mean.count
+}
+
+// ─── Records ─────────────────────────────────────────────────────────────────
+
+export interface DayRecord {
+  day: string
+  value: number
+}
+
+export function peakDay(days: UsageDays, pick: (day: UsageDay) => number): DayRecord {
+  let best: DayRecord = { day: '', value: 0 }
+  for (const [key, day] of Object.entries(days)) {
+    const value = pick(day)
+    if (value > best.value) best = { day: key, value }
+  }
+  return best
+}
+
+/** Prompts sent between 02:00 and 04:59 local — the buckets, not a session span. */
+export function lateNightPrompts(days: UsageDays): number {
+  let total = 0
+  for (const day of Object.values(days)) {
+    for (let hour = 2; hour <= 4; hour++) total += day.hours[hour] ?? 0
+  }
+  return total
+}

package/src/services/usage-history/rollup.ts

@@ -94,8 +94,24 @@ interface TranscriptLine {
   timestamp?: string
 }
 
+export interface TranscriptFileState {
+  /** ms epoch of the previous billed assistant message in this file, for the turn gap. */
+  previousMs: number | null
+}
+
+/**
+ * Anything longer than this is the user walking away, not the model working.
+ * Included, the median turn becomes a measure of lunch breaks.
+ */
+const MAX_TURN_GAP_MS = 5 * 60 * 1000
+
 /** `seen` spans the whole run: resume, fork and compaction re-emit the same billed request across files. */
-export function consumeTranscriptLine(line: string, seen: Set<string>, days: UsageDays): void {
+export function consumeTranscriptLine(
+  line: string,
+  seen: Set<string>,
+  days: UsageDays,
+  state: TranscriptFileState
+): void {
   // ~23k of ~126k lines carry usage; the rest hold base64 thinking blobs. A
   // substring test beats parsing them.
   if (!line.includes('"output_tokens"')) return
@@ -144,15 +160,40 @@ export function consumeTranscriptLine(line: string, seen: Set<string>, days: Usa
   if (model != null && model !== '') bump(day.models, model, total)
   const branch = entry.gitBranch
   if (branch != null && branch !== '') bump(day.branches, branch, total)
+
+  // The gap to the previous billed message in this file. Not prompt-to-response
+  // latency: the user turns in a transcript are mostly tool results, so isolating
+  // a real prompt would mean parsing lines this rollup deliberately skips. What
+  // this measures is the pace of the work cycle, and it is labelled as such.
+  const { previousMs } = state
+  if (previousMs !== null && ms > previousMs && ms - previousMs <= MAX_TURN_GAP_MS) {
+    const gap = ms - previousMs
+    day.turnMs.sum += gap
+    day.turnMs.count += 1
+    day.turnMs.max = Math.max(day.turnMs.max, gap)
+  }
+  state.previousMs = ms
+}
+
+interface HistoryLine {
+  display?: string
+  project?: string
+  sessionId?: string
+  timestamp?: number | string
 }
 
-/** `history.jsonl`, the prompt log — the only source that survives transcript pruning. */
+/**
+ * `history.jsonl`, the prompt log — the only source that survives transcript
+ * pruning, and the source of everything on the Activity and Projects pages. Each
+ * line carries the prompt text, its project path and its session id, not just a
+ * timestamp, and the file stays small where the transcripts run to ~90 MB.
+ */
 export function consumeHistoryLine(line: string, days: UsageDays): void {
   if (!line.includes('"timestamp"')) return
 
-  let entry: { timestamp?: number | string }
+  let entry: HistoryLine
   try {
-    entry = JSON.parse(line) as { timestamp?: number | string }
+    entry = JSON.parse(line) as HistoryLine
   } catch {
     return
   }
@@ -162,7 +203,36 @@ export function consumeHistoryLine(line: string, days: UsageDays): void {
   const ms = Number(entry.timestamp)
   if (!Number.isFinite(ms) || ms <= 0) return
 
-  dayAt(days, localDay(new Date(ms))).prompts += 1
+  const at = new Date(ms)
+  const day = dayAt(days, localDay(at))
+  day.prompts += 1
+
+  const hour = at.getHours()
+  day.hours[hour] = (day.hours[hour] ?? 0) + 1
+
+  const { project } = entry
+  if (project != null && project !== '') bump(day.projects, project, 1)
+
+  const { display } = entry
+  if (display != null) {
+    day.promptChars.sum += display.length
+    day.promptChars.count += 1
+    day.promptChars.max = Math.max(day.promptChars.max, display.length)
+  }
+
+  const { sessionId } = entry
+  if (sessionId != null && sessionId !== '') {
+    const session = day.sessions[sessionId]
+    if (session === undefined) {
+      day.sessions[sessionId] = { first: ms, last: ms, prompts: 1 }
+    } else {
+      // A session can span midnight, and each half is recorded against its own
+      // day — so `first` is the first prompt of this session *on this day*.
+      session.first = Math.min(session.first, ms)
+      session.last = Math.max(session.last, ms)
+      session.prompts += 1
+    }
+  }
 }
 
 interface CodexLine {
@@ -224,8 +294,10 @@ async function collectClaude(): Promise<UsageDays> {
   const root = claudeHome()
 
   await forEachFile(findJsonl(join(root, 'projects')), async (path) => {
+    // Per file: a turn gap only means anything inside one transcript.
+    const state: TranscriptFileState = { previousMs: null }
     await readJsonlLines(path, (line) => {
-      consumeTranscriptLine(line, seen, days)
+      consumeTranscriptLine(line, seen, days, state)
     })
   })