From dc8966c403ed697307bd4fe9e11b762fafd60fc6 Mon Sep 17 00:00:00 2001
From: Algis Dumbris <a.dumbris@gmail.com>
Date: Tue, 2 Jun 2026 06:06:16 +0300
Subject: [PATCH] feat(069-B2): usage charts + Usage.vue + Dashboard switcher

Spec 069 Stream B2 (frontend). Surfaces the activity-log usage aggregate
(GET /api/v1/activity/usage, A3) as Web UI graphs.

- usage/CallHistogram.vue, ResponseSizeRanking.vue (size-based token-sink
  proxy, FR-006), ErrorRateChart.vue (+ per-tool p50/p95 latency table),
  Timeline.vue (calls/errors stacked, honors window/filters, FR-008).
- views/Usage.vue: tokens-saved headline from ServerTokenMetrics (FR-007),
  window selector (24h/7d/all), status/sort filters, empty/low-data state
  (FR-009), 30s auto-refresh against the cached snapshot.
- Dashboard.vue: Overview<->Usage switcher (T016); Overview kept via v-show
  so its state survives a round-trip (SC-006); Usage code-split via
  defineAsyncComponent so the chart bundle/fetch don't block first paint (SC-004).
- api.ts getActivityUsage() (T017) + UsageAggregateResponse types.
- utils/usageFormat.ts shared formatters + palette.

Covers T016-T023. Verified with a Playwright sweep (7/7, 0 console errors)
against populated + empty instances; report kept local per QA-report policy.

Related #745
---
 .../src/components/usage/CallHistogram.vue    |  73 ++++++
 .../src/components/usage/ErrorRateChart.vue   |  99 ++++++++
 .../components/usage/ResponseSizeRanking.vue  |  84 +++++++
 frontend/src/components/usage/Timeline.vue    |  92 ++++++++
 frontend/src/services/api.ts                  |  23 +-
 frontend/src/types/api.ts                     |  49 ++++
 frontend/src/utils/usageFormat.ts             |  47 ++++
 frontend/src/views/Dashboard.vue              |  49 +++-
 frontend/src/views/Usage.vue                  | 214 ++++++++++++++++++
 9 files changed, 728 insertions(+), 2 deletions(-)
 create mode 100644 frontend/src/components/usage/CallHistogram.vue
 create mode 100644 frontend/src/components/usage/ErrorRateChart.vue
 create mode 100644 frontend/src/components/usage/ResponseSizeRanking.vue
 create mode 100644 frontend/src/components/usage/Timeline.vue
 create mode 100644 frontend/src/utils/usageFormat.ts
 create mode 100644 frontend/src/views/Usage.vue

diff --git a/frontend/src/components/usage/CallHistogram.vue b/frontend/src/components/usage/CallHistogram.vue
new file mode 100644
index 000000000..8cb0de74c
--- /dev/null
+++ b/frontend/src/components/usage/CallHistogram.vue
@@ -0,0 +1,73 @@
+<template>
+  <div data-test="usage-call-histogram">
+    <div class="flex items-center justify-between mb-2">
+      <h3 class="font-semibold text-sm">Calls per tool</h3>
+      <span class="text-xs opacity-60">{{ tools.length }} tool{{ tools.length === 1 ? '' : 's' }}</span>
+    </div>
+    <div v-if="tools.length === 0" class="text-sm opacity-60 py-8 text-center" data-test="usage-call-histogram-empty">
+      No tool calls in this window.
+    </div>
+    <div v-else class="relative" :style="{ height: chartHeight }">
+      <Bar :data="chartData" :options="chartOptions" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Bar } from 'vue-chartjs'
+import {
+  Chart as ChartJS,
+  BarElement,
+  CategoryScale,
+  LinearScale,
+  Tooltip,
+  Legend,
+} from 'chart.js'
+import type { ChartOptions } from 'chart.js'
+import type { UsageToolStat } from '@/types'
+import { formatNumber, toolLabel, paletteColor } from '@/utils/usageFormat'
+
+ChartJS.register(BarElement, CategoryScale, LinearScale, Tooltip, Legend)
+
+const props = defineProps<{ tools: UsageToolStat[] }>()
+
+// Horizontal bars so long server:tool labels stay readable on high cardinality.
+const chartHeight = computed(() => `${Math.max(160, props.tools.length * 28 + 40)}px`)
+
+const chartData = computed(() => ({
+  labels: props.tools.map(t => toolLabel(t.server, t.tool)),
+  datasets: [
+    {
+      label: 'Calls',
+      data: props.tools.map(t => t.calls),
+      backgroundColor: props.tools.map((_, i) => paletteColor(i)),
+      borderWidth: 0,
+      borderRadius: 3,
+    },
+  ],
+}))
+
+const chartOptions = computed<ChartOptions<'bar'>>(() => ({
+  indexAxis: 'y',
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: { display: false },
+    tooltip: {
+      callbacks: {
+        label: (ctx) => {
+          const t = props.tools[ctx.dataIndex]
+          if (!t) return ''
+          const errPart = t.errors > 0 ? ` · ${formatNumber(t.errors)} errors` : ''
+          return `${formatNumber(t.calls)} calls${errPart}`
+        },
+      },
+    },
+  },
+  scales: {
+    x: { beginAtZero: true, ticks: { callback: (v) => formatNumber(Number(v)) } },
+    y: { ticks: { autoSkip: false, font: { size: 11 } } },
+  },
+}))
+</script>
diff --git a/frontend/src/components/usage/ErrorRateChart.vue b/frontend/src/components/usage/ErrorRateChart.vue
new file mode 100644
index 000000000..0637fa0ad
--- /dev/null
+++ b/frontend/src/components/usage/ErrorRateChart.vue
@@ -0,0 +1,99 @@
+<template>
+  <div data-test="usage-error-rate-chart">
+    <h3 class="font-semibold text-sm mb-2">Errors &amp; latency</h3>
+    <div v-if="tools.length === 0" class="text-sm opacity-60 py-8 text-center" data-test="usage-error-rate-empty">
+      No tool calls in this window.
+    </div>
+    <template v-else>
+      <!-- Error rate per tool -->
+      <div class="relative mb-4" :style="{ height: chartHeight }">
+        <Bar :data="chartData" :options="chartOptions" />
+      </div>
+      <!-- Per-tool p50/p95 latency (FR: tail-latency visibility, T019) -->
+      <div class="overflow-x-auto">
+        <table class="table table-xs" data-test="usage-latency-table">
+          <thead>
+            <tr>
+              <th>Tool</th>
+              <th class="text-right">p50</th>
+              <th class="text-right">p95</th>
+              <th class="text-right">Err%</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr v-for="t in latencyRows" :key="`${t.server}:${t.tool}`">
+              <td class="font-mono text-xs truncate max-w-[12rem]">{{ toolLabel(t.server, t.tool) }}</td>
+              <td class="text-right font-mono text-xs">{{ formatLatency(t.p50_ms) }}</td>
+              <td class="text-right font-mono text-xs">{{ formatLatency(t.p95_ms) }}</td>
+              <td class="text-right font-mono text-xs" :class="t.error_rate > 0 ? 'text-error' : 'opacity-60'">
+                {{ (t.error_rate * 100).toFixed(1) }}%
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Bar } from 'vue-chartjs'
+import {
+  Chart as ChartJS,
+  BarElement,
+  CategoryScale,
+  LinearScale,
+  Tooltip,
+  Legend,
+} from 'chart.js'
+import type { ChartOptions } from 'chart.js'
+import type { UsageToolStat } from '@/types'
+import { formatNumber, formatLatency, toolLabel } from '@/utils/usageFormat'
+
+ChartJS.register(BarElement, CategoryScale, LinearScale, Tooltip, Legend)
+
+const props = defineProps<{ tools: UsageToolStat[] }>()
+
+const chartHeight = computed(() => `${Math.max(140, props.tools.length * 24 + 40)}px`)
+
+// Worst-offenders first in the latency table; cap the visible rows.
+const latencyRows = computed(() =>
+  [...props.tools].sort((a, b) => b.p95_ms - a.p95_ms).slice(0, 12)
+)
+
+const chartData = computed(() => ({
+  labels: props.tools.map(t => toolLabel(t.server, t.tool)),
+  datasets: [
+    {
+      label: 'Error rate %',
+      data: props.tools.map(t => +(t.error_rate * 100).toFixed(2)),
+      backgroundColor: props.tools.map(t => (t.error_rate > 0 ? '#ef4444' : '#22c55e')),
+      borderWidth: 0,
+      borderRadius: 3,
+    },
+  ],
+}))
+
+const chartOptions = computed<ChartOptions<'bar'>>(() => ({
+  indexAxis: 'y',
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: { display: false },
+    tooltip: {
+      callbacks: {
+        label: (ctx) => {
+          const t = props.tools[ctx.dataIndex]
+          if (!t) return ''
+          return `${(t.error_rate * 100).toFixed(1)}% (${formatNumber(t.errors)}/${formatNumber(t.calls)})`
+        },
+      },
+    },
+  },
+  scales: {
+    x: { beginAtZero: true, max: 100, ticks: { callback: (v) => `${v}%` } },
+    y: { ticks: { autoSkip: false, font: { size: 11 } } },
+  },
+}))
+</script>
diff --git a/frontend/src/components/usage/ResponseSizeRanking.vue b/frontend/src/components/usage/ResponseSizeRanking.vue
new file mode 100644
index 000000000..88ab8fc42
--- /dev/null
+++ b/frontend/src/components/usage/ResponseSizeRanking.vue
@@ -0,0 +1,84 @@
+<template>
+  <div data-test="usage-response-size-ranking">
+    <div class="flex items-center justify-between mb-1">
+      <h3 class="font-semibold text-sm">Token sinks</h3>
+      <span class="text-xs opacity-60">by response size</span>
+    </div>
+    <!-- FR-006: response size is a size-based proxy for token cost, not a real
+         tokenizer count. Make that explicit so the number isn't mistaken for tokens. -->
+    <p class="text-xs opacity-50 mb-2">
+      Ranked by total response bytes (size-based proxy for token cost).
+    </p>
+    <div v-if="ranked.length === 0" class="text-sm opacity-60 py-8 text-center" data-test="usage-response-size-ranking-empty">
+      No sized responses in this window.
+    </div>
+    <div v-else class="relative" :style="{ height: chartHeight }">
+      <Bar :data="chartData" :options="chartOptions" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Bar } from 'vue-chartjs'
+import {
+  Chart as ChartJS,
+  BarElement,
+  CategoryScale,
+  LinearScale,
+  Tooltip,
+  Legend,
+} from 'chart.js'
+import type { ChartOptions } from 'chart.js'
+import type { UsageToolStat } from '@/types'
+import { formatBytes, toolLabel, paletteColor } from '@/utils/usageFormat'
+
+ChartJS.register(BarElement, CategoryScale, LinearScale, Tooltip, Legend)
+
+const props = defineProps<{ tools: UsageToolStat[] }>()
+
+// Rank by total response bytes descending; drop tools with no sized output.
+const ranked = computed(() =>
+  [...props.tools]
+    .filter(t => t.total_resp_bytes > 0)
+    .sort((a, b) => b.total_resp_bytes - a.total_resp_bytes)
+)
+
+const chartHeight = computed(() => `${Math.max(160, ranked.value.length * 28 + 40)}px`)
+
+const chartData = computed(() => ({
+  labels: ranked.value.map(t => toolLabel(t.server, t.tool)),
+  datasets: [
+    {
+      label: 'Total response bytes',
+      data: ranked.value.map(t => t.total_resp_bytes),
+      backgroundColor: ranked.value.map((_, i) => paletteColor(i)),
+      borderWidth: 0,
+      borderRadius: 3,
+    },
+  ],
+}))
+
+const chartOptions = computed<ChartOptions<'bar'>>(() => ({
+  indexAxis: 'y',
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: { display: false },
+    tooltip: {
+      callbacks: {
+        label: (ctx) => {
+          const t = ranked.value[ctx.dataIndex]
+          if (!t) return ''
+          const avg = t.avg_resp_bytes != null ? ` · avg ${formatBytes(t.avg_resp_bytes)}` : ''
+          return `${formatBytes(t.total_resp_bytes)} total${avg}`
+        },
+      },
+    },
+  },
+  scales: {
+    x: { beginAtZero: true, ticks: { callback: (v) => formatBytes(Number(v)) } },
+    y: { ticks: { autoSkip: false, font: { size: 11 } } },
+  },
+}))
+</script>
diff --git a/frontend/src/components/usage/Timeline.vue b/frontend/src/components/usage/Timeline.vue
new file mode 100644
index 000000000..f2e7ccc7d
--- /dev/null
+++ b/frontend/src/components/usage/Timeline.vue
@@ -0,0 +1,92 @@
+<template>
+  <div data-test="usage-timeline">
+    <div class="flex items-center justify-between mb-2">
+      <h3 class="font-semibold text-sm">Activity over time</h3>
+      <span class="text-xs opacity-60">{{ windowLabel }}</span>
+    </div>
+    <div v-if="buckets.length === 0" class="text-sm opacity-60 py-8 text-center" data-test="usage-timeline-empty">
+      No activity in this window.
+    </div>
+    <div v-else class="relative" style="height: 220px">
+      <Bar :data="chartData" :options="chartOptions" />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Bar } from 'vue-chartjs'
+import {
+  Chart as ChartJS,
+  BarElement,
+  CategoryScale,
+  LinearScale,
+  Tooltip,
+  Legend,
+} from 'chart.js'
+import type { ChartOptions } from 'chart.js'
+import type { UsageTimeBucket, UsageWindow } from '@/types'
+import { formatNumber } from '@/utils/usageFormat'
+
+ChartJS.register(BarElement, CategoryScale, LinearScale, Tooltip, Legend)
+
+const props = defineProps<{ buckets: UsageTimeBucket[]; window: UsageWindow }>()
+
+const windowLabel = computed(() => {
+  switch (props.window) {
+    case '24h': return 'Last 24 hours'
+    case '7d': return 'Last 7 days'
+    default: return 'All time'
+  }
+})
+
+// Coarser label for wider windows; the buckets themselves come from the backend.
+function bucketLabel(iso: string): string {
+  const d = new Date(iso)
+  if (Number.isNaN(d.getTime())) return iso
+  if (props.window === '24h') {
+    return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
+  }
+  return d.toLocaleDateString([], { month: 'short', day: 'numeric' })
+}
+
+const chartData = computed(() => ({
+  labels: props.buckets.map(b => bucketLabel(b.start)),
+  datasets: [
+    {
+      label: 'Calls',
+      data: props.buckets.map(b => b.calls - b.errors),
+      backgroundColor: '#3b82f6',
+      borderWidth: 0,
+      stack: 'activity',
+    },
+    {
+      label: 'Errors',
+      data: props.buckets.map(b => b.errors),
+      backgroundColor: '#ef4444',
+      borderWidth: 0,
+      stack: 'activity',
+    },
+  ],
+}))
+
+const chartOptions = computed<ChartOptions<'bar'>>(() => ({
+  responsive: true,
+  maintainAspectRatio: false,
+  plugins: {
+    legend: { display: true, position: 'bottom', labels: { boxWidth: 12, font: { size: 11 } } },
+    tooltip: {
+      callbacks: {
+        footer: (items) => {
+          const b = props.buckets[items[0]?.dataIndex ?? -1]
+          return b ? `Total: ${formatNumber(b.calls)} calls` : ''
+        },
+      },
+    },
+  },
+  scales: {
+    x: { stacked: true, ticks: { maxRotation: 0, autoSkip: true, font: { size: 10 } } },
+    y: { stacked: true, beginAtZero: true, ticks: { callback: (v) => formatNumber(Number(v)) } },
+  },
+}))
+</script>
diff --git a/frontend/src/services/api.ts b/frontend/src/services/api.ts
index 0fc3370b9..d9173c418 100644
--- a/frontend/src/services/api.ts
+++ b/frontend/src/services/api.ts
@@ -1,4 +1,4 @@
-import type { APIResponse, Server, Tool, ToolApproval, SearchResult, StatusUpdate, SecretRef, MigrationAnalysis, ConfigSecretsResponse, GetToolCallsResponse, GetToolCallDetailResponse, GetServerToolCallsResponse, GetConfigResponse, ValidateConfigResponse, ConfigApplyResult, ServerTokenMetrics, GetRegistriesResponse, SearchRegistryServersResponse, GetSessionsResponse, GetSessionDetailResponse, InfoResponse, ActivityListResponse, ActivityDetailResponse, ActivitySummaryResponse, ImportResponse, AgentTokenInfo, CreateAgentTokenRequest, CreateAgentTokenResponse, RoutingInfo, ConnectStatusResponse, ConnectResult, OnboardingStateResponse, OnboardingMarkRequest, DiagnosticFixResponse, GlobalToolsResponse } from '@/types'
+import type { APIResponse, Server, Tool, ToolApproval, SearchResult, StatusUpdate, SecretRef, MigrationAnalysis, ConfigSecretsResponse, GetToolCallsResponse, GetToolCallDetailResponse, GetServerToolCallsResponse, GetConfigResponse, ValidateConfigResponse, ConfigApplyResult, ServerTokenMetrics, GetRegistriesResponse, SearchRegistryServersResponse, GetSessionsResponse, GetSessionDetailResponse, InfoResponse, ActivityListResponse, ActivityDetailResponse, ActivitySummaryResponse, ImportResponse, AgentTokenInfo, CreateAgentTokenRequest, CreateAgentTokenResponse, RoutingInfo, ConnectStatusResponse, ConnectResult, OnboardingStateResponse, OnboardingMarkRequest, DiagnosticFixResponse, GlobalToolsResponse, UsageAggregateResponse, UsageWindow, UsageSort, UsageStatus } from '@/types'
 
 // Event types for API service
 export interface APIAuthEvent {
@@ -758,6 +758,27 @@ class APIService {
     return this.request<ActivitySummaryResponse>(`/api/v1/activity/summary?period=${period}`)
   }
 
+  // Usage statistics aggregate for the Web UI usage graphs (Spec 069).
+  async getActivityUsage(params?: {
+    window?: UsageWindow
+    server?: string
+    tool?: string
+    status?: UsageStatus
+    top?: number
+    sort?: UsageSort
+  }): Promise<APIResponse<UsageAggregateResponse>> {
+    const searchParams = new URLSearchParams()
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== '') {
+          searchParams.append(key, String(value))
+        }
+      })
+    }
+    const qs = searchParams.toString()
+    return this.request<UsageAggregateResponse>(`/api/v1/activity/usage${qs ? '?' + qs : ''}`)
+  }
+
   getActivityExportUrl(params: {
     format: 'json' | 'csv'
     type?: string
diff --git a/frontend/src/types/api.ts b/frontend/src/types/api.ts
index 6a341f462..359b5dfe2 100644
--- a/frontend/src/types/api.ts
+++ b/frontend/src/types/api.ts
@@ -419,6 +419,55 @@ export interface ServerTokenMetrics {
   per_server_tool_list_sizes: Record<string, number>
 }
 
+// Usage statistics aggregate — GET /api/v1/activity/usage (Spec 069).
+// Mirrors contracts.UsageAggregateResponse. Per-tool metrics are
+// lifetime-cumulative; `window` scopes the timeline + the tool-list membership.
+export interface UsageToolStat {
+  server: string
+  tool: string
+  calls: number
+  errors: number
+  error_rate: number
+  blocked: number
+  total_resp_bytes: number
+  avg_resp_bytes: number | null   // null when only legacy 0-byte calls exist
+  total_req_bytes: number
+  avg_req_bytes: number | null
+  sized_calls: number
+  p50_ms: number
+  p95_ms: number
+  last_used: string
+}
+
+export interface UsageOtherBucket {
+  tools_folded: number
+  calls: number
+  total_resp_bytes: number
+}
+
+export interface UsageTimeBucket {
+  start: string
+  calls: number
+  errors: number
+  total_resp_bytes: number
+}
+
+export interface UsageAggregateResponse {
+  window: string
+  generated_at: string
+  freshness_ms: number
+  token_source: string              // "bytes" — size-based proxy (FR-006)
+  tokens_saved: number              // echoed from ServerTokenMetrics (FR-007)
+  tokens_saved_percentage: number
+  tools: UsageToolStat[]
+  other?: UsageOtherBucket | null   // present only when list truncated to top-N
+  timeline: UsageTimeBucket[]
+}
+
+export type UsageWindow = '24h' | '7d' | 'all'
+export type UsageSort = 'calls' | 'resp_bytes' | 'error_rate' | 'p95'
+export type UsageStatus = 'success' | 'error' | 'blocked'
+
 export interface ToolCallRecord {
   id: string
   server_id: string
diff --git a/frontend/src/utils/usageFormat.ts b/frontend/src/utils/usageFormat.ts
new file mode 100644
index 000000000..79177865a
--- /dev/null
+++ b/frontend/src/utils/usageFormat.ts
@@ -0,0 +1,47 @@
+// Shared formatting helpers + colour palette for the Usage graphs (Spec 069 B2).
+// Kept dependency-free so the usage chart components can import them without
+// pulling in Dashboard internals.
+
+/** Compact number: 1234 -> "1.2K", 2_500_000 -> "2.5M". */
+export function formatNumber(num: number): string {
+  if (!Number.isFinite(num)) return '0'
+  if (Math.abs(num) >= 1_000_000) return `${(num / 1_000_000).toFixed(1)}M`
+  if (Math.abs(num) >= 1_000) return `${(num / 1_000).toFixed(1)}K`
+  return String(num)
+}
+
+/** Human byte size: 0 -> "0 B", 2048 -> "2.0 KB". */
+export function formatBytes(bytes: number | null | undefined): string {
+  if (bytes == null || !Number.isFinite(bytes) || bytes <= 0) return '0 B'
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let i = 0
+  let v = bytes
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024
+    i++
+  }
+  return `${i === 0 ? v : v.toFixed(1)} ${units[i]}`
+}
+
+/** Latency in ms: 0 -> "0 ms", 1500 -> "1.5 s". */
+export function formatLatency(ms: number | null | undefined): string {
+  if (ms == null || !Number.isFinite(ms) || ms <= 0) return '0 ms'
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)} s`
+  return `${Math.round(ms)} ms`
+}
+
+/** A short, readable label for a (server, tool) pair. */
+export function toolLabel(server: string, tool: string): string {
+  return `${server}:${tool}`
+}
+
+/** Stable, colour-blind-friendly palette shared across the usage charts. */
+export const USAGE_PALETTE = [
+  '#3b82f6', '#10b981', '#f59e0b', '#ec4899', '#8b5cf6',
+  '#06b6d4', '#ef4444', '#14b8a6', '#f97316', '#a855f7',
+  '#6366f1', '#84cc16', '#f43f5e', '#0ea5e9', '#22c55e', '#eab308',
+]
+
+export function paletteColor(index: number): string {
+  return USAGE_PALETTE[index % USAGE_PALETTE.length]
+}
diff --git a/frontend/src/views/Dashboard.vue b/frontend/src/views/Dashboard.vue
index 379674ed6..22fac07e5 100644
--- a/frontend/src/views/Dashboard.vue
+++ b/frontend/src/views/Dashboard.vue
@@ -3,6 +3,38 @@
     <!-- Telemetry Notice Banner -->
     <TelemetryBanner />
 
+    <!-- Overview ↔ Usage switcher (Spec 069 T016) -->
+    <div role="tablist" class="tabs tabs-boxed w-fit" data-test="dashboard-view-switcher">
+      <a
+        role="tab"
+        class="tab"
+        :class="activeView === 'overview' ? 'tab-active' : ''"
+        data-test="dashboard-tab-overview"
+        @click="activeView = 'overview'"
+      >Overview</a>
+      <a
+        role="tab"
+        class="tab"
+        :class="activeView === 'usage' ? 'tab-active' : ''"
+        data-test="dashboard-tab-usage"
+        @click="selectUsage"
+      >Usage</a>
+    </div>
+
+    <!-- Usage view: lazy-mounted on first switch so the chart bundle and the
+         usage fetch don't block Dashboard first paint (SC-004). Kept alive with
+         v-show after mount so re-switching is instant. -->
+    <div v-if="usageEverActive" v-show="activeView === 'usage'" data-test="dashboard-usage-panel">
+      <Suspense>
+        <UsageView />
+        <template #fallback>
+          <div class="flex justify-center py-16"><span class="loading loading-spinner loading-lg"></span></div>
+        </template>
+      </Suspense>
+    </div>
+
+    <!-- Overview: v-show (not v-if) so its state survives a switch to Usage and back (SC-006). -->
+    <div v-show="activeView === 'overview'" class="space-y-6" data-test="dashboard-overview-panel">
     <!-- Servers Needing Attention Banner (using unified health status) -->
     <div
       v-if="serversNeedingAttention.length > 0"
@@ -376,6 +408,8 @@
 
     <!-- Hints Panel (Bottom of Page) -->
     <CollapsibleHintsPanel :hints="dashboardHints" />
+    </div>
+    <!-- /Overview panel -->
 
     <!-- Modals -->
     <ConnectModal :show="showConnectModal" @close="showConnectModal = false" />
@@ -385,7 +419,7 @@
 </template>
 
 <script setup lang="ts">
-import { computed, ref, watch, onMounted, onUnmounted } from 'vue'
+import { computed, ref, watch, onMounted, onUnmounted, defineAsyncComponent } from 'vue'
 import { useServersStore } from '@/stores/servers'
 import { useSystemStore } from '@/stores/system'
 import { useSecurityScannerStatus, refreshSecurityScannerStatus } from '@/composables/useSecurityScannerStatus'
@@ -401,10 +435,23 @@ import { useOnboardingStore } from '@/stores/onboarding'
 import type { Hint } from '@/components/CollapsibleHintsPanel.vue'
 import type { ClientStatus } from '@/types'
 
+// Usage view is code-split so chart.js + the usage fetch stay out of the
+// Dashboard's first-paint critical path (Spec 069 SC-004).
+const UsageView = defineAsyncComponent(() => import('@/views/Usage.vue'))
+
 const serversStore = useServersStore()
 const systemStore = useSystemStore()
 const onboardingStore = useOnboardingStore()
 
+// Overview ↔ Usage switcher state (Spec 069 T016). `usageEverActive` gates the
+// first mount; `activeView` then toggles via v-show so both panels keep state.
+const activeView = ref<'overview' | 'usage'>('overview')
+const usageEverActive = ref(false)
+function selectUsage() {
+  usageEverActive.value = true
+  activeView.value = 'usage'
+}
+
 // Modal state
 const showConnectModal = ref(false)
 const showAddServer = ref(false)
diff --git a/frontend/src/views/Usage.vue b/frontend/src/views/Usage.vue
new file mode 100644
index 000000000..f4d99425e
--- /dev/null
+++ b/frontend/src/views/Usage.vue
@@ -0,0 +1,214 @@
+<template>
+  <div class="space-y-6" data-test="usage-view">
+    <!-- Controls: window + filters -->
+    <div class="flex flex-wrap items-center gap-3">
+      <div class="join" data-test="usage-window-selector">
+        <button
+          v-for="w in windows"
+          :key="w.value"
+          class="btn btn-sm join-item"
+          :class="window === w.value ? 'btn-primary' : 'btn-ghost'"
+          :data-test="`usage-window-${w.value}`"
+          @click="setWindow(w.value)"
+        >
+          {{ w.label }}
+        </button>
+      </div>
+
+      <select v-model="status" class="select select-sm select-bordered" data-test="usage-status-filter" @change="reload">
+        <option value="">All statuses</option>
+        <option value="success">Success</option>
+        <option value="error">Errors</option>
+        <option value="blocked">Blocked</option>
+      </select>
+
+      <select v-model="sort" class="select select-sm select-bordered" data-test="usage-sort" @change="reload">
+        <option value="resp_bytes">Sort: response size</option>
+        <option value="calls">Sort: calls</option>
+        <option value="error_rate">Sort: error rate</option>
+        <option value="p95">Sort: p95 latency</option>
+      </select>
+
+      <span v-if="data" class="text-xs opacity-50 ml-auto" data-test="usage-freshness">
+        Updated {{ freshnessLabel }}
+      </span>
+    </div>
+
+    <!-- Tokens-saved headline (FR-007) -->
+    <div v-if="data" class="stats stats-vertical sm:stats-horizontal shadow w-full" data-test="usage-tokens-saved">
+      <div class="stat">
+        <div class="stat-title">Tokens saved</div>
+        <div class="stat-value text-success">{{ formatNumber(data.tokens_saved) }}</div>
+        <div class="stat-desc">{{ data.tokens_saved_percentage.toFixed(1) }}% reduction via BM25 discovery</div>
+      </div>
+      <div class="stat">
+        <div class="stat-title">Tool calls</div>
+        <div class="stat-value">{{ formatNumber(totalCalls) }}</div>
+        <div class="stat-desc">{{ data.tools.length }} active tool{{ data.tools.length === 1 ? '' : 's' }} ({{ windowLabel }})</div>
+      </div>
+      <div class="stat">
+        <div class="stat-title">Errors</div>
+        <div class="stat-value" :class="totalErrors > 0 ? 'text-error' : ''">{{ formatNumber(totalErrors) }}</div>
+        <div class="stat-desc">{{ overallErrorRate }}% overall error rate</div>
+      </div>
+    </div>
+
+    <!-- Loading -->
+    <div v-if="loading && !data" class="flex justify-center py-16" data-test="usage-loading">
+      <span class="loading loading-spinner loading-lg"></span>
+    </div>
+
+    <!-- Error -->
+    <div v-else-if="error" class="alert alert-error" data-test="usage-error">
+      <span>{{ error }}</span>
+      <button class="btn btn-sm" @click="reload">Retry</button>
+    </div>
+
+    <!-- Empty / low-data state (FR-009) -->
+    <div
+      v-else-if="data && isEmpty"
+      class="card bg-base-200 border border-base-300"
+      data-test="usage-empty-state"
+    >
+      <div class="card-body items-center text-center py-12">
+        <svg class="w-12 h-12 opacity-40" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M9 19v-6a2 2 0 00-2-2H5a2 2 0 00-2 2v6a2 2 0 002 2h2a2 2 0 002-2zm0 0V9a2 2 0 012-2h2a2 2 0 012 2v10m-6 0a2 2 0 002 2h2a2 2 0 002-2m0 0V5a2 2 0 012-2h2a2 2 0 012 2v14a2 2 0 01-2 2h-2a2 2 0 01-2-2z" />
+        </svg>
+        <h3 class="font-semibold text-lg mt-2">No usage data yet</h3>
+        <p class="text-sm opacity-60 max-w-md">
+          Once your agents start calling tools through the proxy, you'll see call volume,
+          token sinks, error rates and a timeline here. Try widening the window or clearing filters.
+        </p>
+        <button v-if="window !== 'all' || status" class="btn btn-sm btn-primary mt-2" data-test="usage-empty-widen" @click="resetFilters">
+          Show all time
+        </button>
+      </div>
+    </div>
+
+    <!-- Charts grid -->
+    <div v-else-if="data" class="grid grid-cols-1 lg:grid-cols-2 gap-6" data-test="usage-charts">
+      <div class="card bg-base-100 shadow">
+        <div class="card-body p-4">
+          <CallHistogram :tools="data.tools" />
+        </div>
+      </div>
+      <div class="card bg-base-100 shadow">
+        <div class="card-body p-4">
+          <ResponseSizeRanking :tools="data.tools" />
+        </div>
+      </div>
+      <div class="card bg-base-100 shadow">
+        <div class="card-body p-4">
+          <ErrorRateChart :tools="data.tools" />
+        </div>
+      </div>
+      <div class="card bg-base-100 shadow">
+        <div class="card-body p-4">
+          <Timeline :buckets="data.timeline" :window="window" />
+        </div>
+      </div>
+
+      <!-- "other" fold note when the per-tool list was truncated -->
+      <div v-if="data.other" class="lg:col-span-2 text-xs opacity-50 text-center" data-test="usage-other-note">
+        + {{ data.other.tools_folded }} more tool{{ data.other.tools_folded === 1 ? '' : 's' }}
+        ({{ formatNumber(data.other.calls) }} calls) folded into “other”.
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, onMounted, onUnmounted } from 'vue'
+import api from '@/services/api'
+import type { UsageAggregateResponse, UsageWindow, UsageSort, UsageStatus } from '@/types'
+import { formatNumber } from '@/utils/usageFormat'
+import CallHistogram from '@/components/usage/CallHistogram.vue'
+import ResponseSizeRanking from '@/components/usage/ResponseSizeRanking.vue'
+import ErrorRateChart from '@/components/usage/ErrorRateChart.vue'
+import Timeline from '@/components/usage/Timeline.vue'
+
+const windows: { value: UsageWindow; label: string }[] = [
+  { value: '24h', label: '24h' },
+  { value: '7d', label: '7d' },
+  { value: 'all', label: 'All' },
+]
+
+const window = ref<UsageWindow>('24h')
+const status = ref<UsageStatus | ''>('')
+const sort = ref<UsageSort>('resp_bytes')
+
+const data = ref<UsageAggregateResponse | null>(null)
+const loading = ref(false)
+const error = ref<string | null>(null)
+let refreshTimer: ReturnType<typeof setInterval> | null = null
+
+const windowLabel = computed(() => {
+  switch (window.value) {
+    case '24h': return 'last 24h'
+    case '7d': return 'last 7d'
+    default: return 'all time'
+  }
+})
+
+const totalCalls = computed(() => data.value?.tools.reduce((s, t) => s + t.calls, 0) ?? 0)
+const totalErrors = computed(() => data.value?.tools.reduce((s, t) => s + t.errors, 0) ?? 0)
+const overallErrorRate = computed(() => {
+  const c = totalCalls.value
+  return c > 0 ? ((totalErrors.value / c) * 100).toFixed(1) : '0.0'
+})
+
+const isEmpty = computed(() => {
+  if (!data.value) return false
+  return data.value.tools.length === 0 && data.value.timeline.length === 0
+})
+
+const freshnessLabel = computed(() => {
+  const ms = data.value?.freshness_ms ?? 0
+  if (ms < 1000) return 'just now'
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s ago`
+  return `${Math.round(ms / 60_000)}m ago`
+})
+
+async function reload() {
+  loading.value = true
+  error.value = null
+  try {
+    const resp = await api.getActivityUsage({
+      window: window.value,
+      status: status.value || undefined,
+      sort: sort.value,
+    })
+    if (resp.success && resp.data) {
+      data.value = resp.data
+    } else {
+      error.value = resp.error || 'Failed to load usage data'
+    }
+  } catch (e) {
+    error.value = e instanceof Error ? e.message : 'Failed to load usage data'
+  } finally {
+    loading.value = false
+  }
+}
+
+function setWindow(w: UsageWindow) {
+  window.value = w
+  reload()
+}
+
+function resetFilters() {
+  window.value = 'all'
+  status.value = ''
+  reload()
+}
+
+onMounted(() => {
+  reload()
+  // Light auto-refresh so the page stays live without hammering the endpoint
+  // (the backend already serves from a short-TTL cached snapshot).
+  refreshTimer = setInterval(reload, 30_000)
+})
+
+onUnmounted(() => {
+  if (refreshTimer) clearInterval(refreshTimer)
+})
+</script>