feat: enhance usage analytics dashboard (#666)

- visualize input, output, and cache token segments in usage charts
- add usage period selector for 7d, 30d, 90d, and 365d
- guard usage stats against stale overlapping period requests
- normalize blank model usage into unknown buckets
- add client and server coverage for usage analytics behavior

packages/client/src/components/hermes/usage/DailyTrend.vue

@@ -25,7 +25,7 @@ function cacheHitRate(d: { input_tokens: number; cache_read_tokens: number }): s
 }
 
 const maxTokens = computed(() =>
-  Math.max(...usageStore.dailyUsage.map(d => d.input_tokens + d.output_tokens), 1),
+  Math.max(...usageStore.dailyUsage.map(d => d.visualTokens), 1),
 )
 </script>
 
@@ -41,12 +41,25 @@ const maxTokens = computed(() =>
       >
         <div class="bar-track">
           <div
-            class="bar-fill"
-            :style="{
-              height: ((d.input_tokens + d.output_tokens) / maxTokens * 100) + '%',
-              '--output-pct': (d.output_tokens / Math.max(d.input_tokens + d.output_tokens, 1) * 100) + '%',
-            }"
-          />
+            class="bar-stack"
+            :style="{ height: (d.visualTokens / maxTokens * 100) + '%' }"
+          >
+            <div
+              v-if="d.output_tokens > 0"
+              class="bar-segment output"
+              :style="{ height: d.outputPercent + '%' }"
+            />
+            <div
+              v-if="d.input_tokens > 0"
+              class="bar-segment input"
+              :style="{ height: d.inputPercent + '%' }"
+            />
+            <div
+              v-if="d.cache_read_tokens > 0"
+              class="bar-segment cache"
+              :style="{ height: d.cachePercent + '%' }"
+            />
+          </div>
         </div>
         <div class="bar-tooltip">
           <div class="tooltip-date">{{ d.date }}</div>
@@ -65,6 +78,12 @@ const maxTokens = computed(() =>
       <span>{{ usageStore.dailyUsage[usageStore.dailyUsage.length - 1]?.date.slice(5) }}</span>
     </div>
 
+    <div class="chart-legend" aria-label="Token type legend">
+      <div class="legend-item"><span class="legend-swatch input" />{{ t('usage.inputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch output" />{{ t('usage.outputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch cache" />{{ t('usage.cacheRead') }}</div>
+    </div>
+
     <div class="trend-table">
       <table>
         <thead>
@@ -80,7 +99,7 @@ const maxTokens = computed(() =>
           </tr>
         </thead>
         <tbody>
-          <tr v-for="d in [...usageStore.dailyUsage].reverse().slice(0, 30)" :key="d.date">
+          <tr v-for="d in [...usageStore.dailyUsage].reverse()" :key="d.date">
             <td>{{ d.date }}</td>
             <td>{{ formatTokens(d.input_tokens) }}</td>
             <td>{{ formatTokens(d.output_tokens) }}</td>
@@ -135,21 +154,38 @@ const maxTokens = computed(() =>
   border-radius: 2px 2px 0 0;
   display: flex;
   align-items: flex-end;
+  overflow: hidden;
+  position: relative;
 }
 
-.bar-fill {
+.bar-stack {
+  width: 100%;
+  display: flex;
+  flex-direction: column-reverse;
+  justify-content: flex-start;
+  overflow: hidden;
+  transition: height 0.3s ease;
+}
+
+.bar-segment {
   width: 100%;
-  border-radius: 2px 2px 0 0;
   min-height: 0;
   transition: height 0.3s ease;
-  /* Bottom = output (teal), top = input (blue) */
-  background: linear-gradient(
-    to top,
-    #26a69a 0%,
-    #26a69a var(--output-pct, 50%),
-    #5c6bc0 var(--output-pct, 50%),
-    #5c6bc0 100%
-  );
+}
+
+.bar-segment.output,
+.legend-swatch.output {
+  background: #26a69a;
+}
+
+.bar-segment.input,
+.legend-swatch.input {
+  background: #5c6bc0;
+}
+
+.bar-segment.cache,
+.legend-swatch.cache {
+  background: #f6ad55;
 }
 
 .bar-tooltip {
@@ -184,12 +220,10 @@ const maxTokens = computed(() =>
 
 .tooltip-date {
   font-weight: 600;
-  margin-bottom: 2px;
+  margin-bottom: 4px;
 }
 
 .tooltip-row {
-  font-size: 10px;
-  opacity: 0.85;
   line-height: 1.5;
 }
 
@@ -198,46 +232,59 @@ const maxTokens = computed(() =>
   justify-content: space-between;
   font-size: 10px;
   color: $text-muted;
-  margin-top: 4px;
-  margin-bottom: 16px;
+  margin-bottom: 12px;
+}
+
+.chart-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 14px;
+  margin: 0 0 16px;
+  color: $text-muted;
+  font-size: 11px;
+}
+
+.legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.legend-swatch {
+  width: 8px;
+  height: 8px;
+  border-radius: 2px;
+  flex-shrink: 0;
 }
 
 .trend-table {
   overflow-x: auto;
-}
 
-table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 12px;
-}
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 11px;
+  }
 
-thead {
-  position: sticky;
-  top: 0;
-}
+  th,
+  td {
+    text-align: right;
+    padding: 6px 8px;
+    border-bottom: 1px solid $border-color;
+  }
 
-th {
-  text-align: left;
-  padding: 8px 10px;
-  font-weight: 600;
-  color: $text-muted;
-  border-bottom: 1px solid $border-color;
-  background: $bg-card;
-  font-size: 11px;
-  text-transform: uppercase;
-  letter-spacing: 0.3px;
-}
+  th:first-child,
+  td:first-child {
+    text-align: left;
+  }
 
-td {
-  padding: 6px 10px;
-  color: $text-secondary;
-  border-bottom: 1px solid $border-light;
-  font-family: $font-code;
-  font-size: 11px;
-}
+  th {
+    color: $text-muted;
+    font-weight: 500;
+  }
 
-tr:last-child td {
-  border-bottom: none;
+  td {
+    color: $text-secondary;
+  }
 }
 </style>

packages/client/src/components/hermes/usage/ModelBreakdown.vue

@@ -5,28 +5,61 @@ import { useUsageStore } from '@/stores/hermes/usage'
 
 const { t } = useI18n()
 const usageStore = useUsageStore()
-const maxModelTokens = computed(() => Math.max(usageStore.modelUsage[0]?.totalTokens || 0, 1))
+const maxModelTokens = computed(() => Math.max(...usageStore.modelUsage.map(m => m.visualTokens), 1))
 
 function formatTokens(n: number): string {
   if (n >= 1000000) return (n / 1000000).toFixed(1) + 'M'
   if (n >= 1000) return (n / 1000).toFixed(1) + 'K'
   return String(n)
 }
+
+function cacheHitRate(m: { inputTokens: number; cacheTokens: number }): string {
+  const total = m.inputTokens + m.cacheTokens
+  if (total === 0) return '--'
+  return ((m.cacheTokens / total) * 100).toFixed(1) + '%'
+}
 </script>
 
 <template>
   <div class="model-breakdown">
     <h3 class="section-title">{{ t('usage.modelBreakdown') }}</h3>
+
+    <div class="model-legend" aria-label="Token type legend">
+      <div class="legend-item"><span class="legend-swatch input" />{{ t('usage.inputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch output" />{{ t('usage.outputTokens') }}</div>
+      <div class="legend-item"><span class="legend-swatch cache" />{{ t('usage.cacheRead') }}</div>
+    </div>
+
     <div class="model-list">
       <div v-for="m in usageStore.modelUsage" :key="m.model" class="model-row">
-        <span class="model-name">{{ m.model }}</span>
+        <span class="model-swatch" :style="{ background: m.color }" />
+        <span class="model-name" :title="m.model">{{ m.model }}</span>
         <div class="model-bar-wrap">
           <div
             class="model-bar"
-            :style="{ width: (m.totalTokens / maxModelTokens * 100) + '%' }"
-          />
+            :style="{ width: (m.visualTokens / maxModelTokens * 100) + '%' }"
+          >
+            <div
+              v-if="m.inputTokens > 0"
+              class="model-bar-segment input"
+              :style="{ width: m.inputPercent + '%' }"
+            />
+            <div
+              v-if="m.outputTokens > 0"
+              class="model-bar-segment output"
+              :style="{ width: m.outputPercent + '%' }"
+            />
+            <div
+              v-if="m.cacheTokens > 0"
+              class="model-bar-segment cache"
+              :style="{ width: m.cachePercent + '%' }"
+            />
+          </div>
         </div>
-        <span class="model-tokens">{{ formatTokens(m.totalTokens) }}</span>
+        <span class="model-tokens" :title="`${t('usage.inputTokens')}: ${formatTokens(m.inputTokens)} · ${t('usage.outputTokens')}: ${formatTokens(m.outputTokens)} · ${t('usage.cacheRead')}: ${formatTokens(m.cacheTokens)} · ${t('usage.cacheHitRate')}: ${cacheHitRate(m)}`">
+          {{ formatTokens(m.totalTokens) }}
+          <small v-if="m.cacheTokens > 0">+{{ formatTokens(m.cacheTokens) }}</small>
+        </span>
       </div>
     </div>
   </div>
@@ -50,6 +83,44 @@ function formatTokens(n: number): string {
   margin: 0 0 12px;
 }
 
+.model-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px 14px;
+  margin: 0 0 12px;
+  color: $text-muted;
+  font-size: 11px;
+}
+
+.legend-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.legend-swatch,
+.model-swatch {
+  width: 8px;
+  height: 8px;
+  border-radius: 2px;
+  flex-shrink: 0;
+}
+
+.legend-swatch.input,
+.model-bar-segment.input {
+  background: #5c6bc0;
+}
+
+.legend-swatch.output,
+.model-bar-segment.output {
+  background: #26a69a;
+}
+
+.legend-swatch.cache,
+.model-bar-segment.cache {
+  background: #f6ad55;
+}
+
 .model-list {
   display: flex;
   flex-direction: column;
@@ -83,21 +154,29 @@ function formatTokens(n: number): string {
 
 .model-bar {
   height: 100%;
-  background: $text-primary;
   border-radius: 3px;
   min-width: 2px;
   transition: width 0.3s ease;
+  display: flex;
+  overflow: hidden;
+}
 
-  .dark & {
-    background: #66bb6a;
-  }
+.model-bar-segment {
+  height: 100%;
+  min-width: 0;
 }
 
 .model-tokens {
   font-size: 12px;
   color: $text-muted;
-  width: 60px;
+  width: 86px;
   text-align: right;
   flex-shrink: 0;
+
+  small {
+    color: #f6ad55;
+    margin-left: 4px;
+    font-size: 10px;
+  }
 }
 </style>