opencode-plugboard 0.17.0 → 0.18.0

package/src/dashboard/app.js

@@ -0,0 +1,444 @@
+/*
+ * plugboard usage dashboard (#141). Plain browser script, no build step, served as /dashboard/app.js.
+ *
+ * Data comes only from GET /v1/usage, with the key the person typed (kept in sessionStorage). Every
+ * value that came from the server (app names, model ids) reaches the page through textContent or
+ * attributes; nothing here writes markup from a string. The page sends no inline script or style (see page.ts).
+ */
+(function () {
+  "use strict";
+
+  var KEY_STORAGE = "plugboard.usage.key";
+  var COLORS = ["#2f6fdb", "#e0701b", "#2a9d5b", "#b43fa6", "#c99700", "#d6336c", "#15877f", "#6b5ce7"];
+  var CHART_HEIGHT = 220;
+  var MODEL_ROWS = 20;
+  var dark = window.matchMedia("(prefers-color-scheme: dark)");
+
+  var state = { days: 7, report: null, sort: { key: "costUsd", dir: -1 }, charts: [] };
+
+  function $(id) {
+    return document.getElementById(id);
+  }
+
+  /** An element with static attributes and text children (strings become text nodes). */
+  function h(tag, attrs) {
+    var node = document.createElement(tag);
+    var children = Array.prototype.slice.call(arguments, 2);
+    Object.keys(attrs || {}).forEach(function (name) {
+      node.setAttribute(name, attrs[name]);
+    });
+    children.forEach(function (child) {
+      if (child !== null && child !== undefined) node.append(child);
+    });
+    return node;
+  }
+
+  // ---------------------------------------------------------------- formatting
+
+  var integer = new Intl.NumberFormat(undefined);
+  var compact = new Intl.NumberFormat(undefined, { notation: "compact", maximumFractionDigits: 1 });
+  var dollars = new Intl.NumberFormat(undefined, { style: "currency", currency: "USD", maximumFractionDigits: 2 });
+
+  function fmtCount(n) {
+    return n >= 10000 ? compact.format(n) : integer.format(n);
+  }
+  function fmtCost(usd) {
+    if (usd > 0 && usd < 0.005) return "<$0.01";
+    return dollars.format(usd);
+  }
+  function fmtMs(ms) {
+    if (ms === null || ms === undefined) return "n/a";
+    if (ms >= 1000) return (ms / 1000).toFixed(ms >= 10000 ? 0 : 1) + " s";
+    return ms + " ms";
+  }
+  function fmtTime(iso) {
+    return iso ? new Date(iso).toLocaleString() : "never";
+  }
+  function fmtRate(hits, misses) {
+    var total = hits + misses;
+    return total === 0 ? "n/a" : ((hits / total) * 100).toFixed(1) + "%";
+  }
+
+  function tokensOf(counts) {
+    var t = counts.tokens;
+    return t.input + t.cacheRead + t.cacheWrite + t.output + t.reasoning;
+  }
+  function errorsOf(counts) {
+    var e = counts.errors;
+    return e.client + e.server + e.timeout + e.disconnected;
+  }
+
+  /** The UTC calendar day `offset` days from today, YYYY-MM-DD. */
+  function utcDay(offset) {
+    var d = new Date();
+    d.setUTCHours(0, 0, 0, 0);
+    d.setUTCDate(d.getUTCDate() + offset);
+    return d.toISOString().slice(0, 10);
+  }
+
+  // ---------------------------------------------------------------- view state
+
+  function setStatus(text) {
+    $("status").textContent = text;
+  }
+
+  function showSignIn(message) {
+    destroyCharts();
+    state.report = null;
+    $("panel").hidden = true;
+    $("signin").hidden = false;
+    $("auth-error").hidden = !message;
+    $("auth-error").textContent = message || "";
+    $("key").focus();
+  }
+
+  function showPanel() {
+    $("signin").hidden = true;
+    $("panel").hidden = false;
+    Array.prototype.forEach.call(document.querySelectorAll("[data-days]"), function (button) {
+      button.setAttribute("aria-pressed", String(Number(button.getAttribute("data-days")) === state.days));
+    });
+  }
+
+  // ---------------------------------------------------------------- loading
+
+  async function load() {
+    var stored = sessionStorage.getItem(KEY_STORAGE);
+    if (stored === null) return showSignIn("");
+    showPanel();
+    var from = utcDay(-(state.days - 1));
+    var to = utcDay(0);
+    setStatus("Loading " + from + " to " + to + " (UTC)...");
+    var response;
+    try {
+      response = await fetch("/v1/usage?from=" + from + "&to=" + to, {
+        headers: stored === "" ? {} : { authorization: "Bearer " + stored },
+        cache: "no-store",
+        credentials: "omit",
+        referrerPolicy: "no-referrer",
+      });
+    } catch (error) {
+      setStatus("Could not reach plugboard. Check the connection and refresh.");
+      return;
+    }
+    if (response.status === 401 || response.status === 403) {
+      sessionStorage.removeItem(KEY_STORAGE);
+      showSignIn(response.status === 401 ? "That key was not accepted." : "This key may not read usage.");
+      return;
+    }
+    if (!response.ok) {
+      setStatus("plugboard answered " + response.status + ". Refresh to try again.");
+      return;
+    }
+    state.report = await response.json();
+    render();
+    setStatus("Updated " + new Date().toLocaleTimeString() + ". " + from + " to " + to + " (UTC days).");
+  }
+
+  function render() {
+    if (!state.report) return;
+    renderTotals();
+    renderApps();
+    renderCharts();
+    renderModels();
+  }
+
+  // ---------------------------------------------------------------- totals
+
+  function stat(label, value, note) {
+    return h("div", { class: "card stat" }, h("span", { class: "label" }, label), h("strong", null, value), note ? h("span", { class: "muted" }, note) : null);
+  }
+
+  function renderTotals() {
+    var t = state.report.totals;
+    var e = t.errors;
+    var cards = [
+      stat("Requests", fmtCount(t.requests), null),
+      stat("Tokens", fmtCount(tokensOf(t)), "input " + fmtCount(t.tokens.input) + ", output " + fmtCount(t.tokens.output + t.tokens.reasoning)),
+      stat("Estimated cost", fmtCost(t.costUsd), t.unpricedRequests > 0 ? t.unpricedRequests + " call(s) had no price" : null),
+      stat("Errors", fmtCount(errorsOf(t)), "client " + e.client + ", server " + e.server + ", timeout " + e.timeout + ", disconnected " + e.disconnected),
+      stat("Cache hit rate", fmtRate(t.cacheHits, t.cacheMisses), t.cacheHits + " hits, " + t.cacheMisses + " misses"),
+      stat("Fallbacks", fmtCount(t.fallbacks), "retries on another target"),
+      stat("Rate limited (429)", fmtCount(t.limited), null),
+      stat("p95 latency", t.latency.p95Ms === null ? "n/a" : "\u2264 " + fmtMs(t.latency.p95Ms), "estimate from buckets"),
+    ];
+    $("totals").replaceChildren(...cards);
+  }
+
+  // ---------------------------------------------------------------- tables
+
+  function sortable(label, key) {
+    var active = state.sort.key === key;
+    var arrow = active ? (state.sort.dir < 0 ? " \u2193" : " \u2191") : "";
+    var button = h("button", { type: "button", "data-sort": key }, label + arrow);
+    return h("th", { class: "num", "aria-sort": active ? (state.sort.dir < 0 ? "descending" : "ascending") : "none" }, button);
+  }
+
+  var SORT_VALUE = {
+    requests: function (t) {
+      return t.requests;
+    },
+    tokens: tokensOf,
+    costUsd: function (t) {
+      return t.costUsd;
+    },
+  };
+
+  function renderApps() {
+    var apps = state.report.apps;
+    var names = Object.keys(apps).sort();
+    var table = $("apps");
+    table.replaceChildren();
+    if (names.length === 0) {
+      table.append(h("tr", null, h("td", null, "No usage in this range.")));
+      return;
+    }
+    var value = SORT_VALUE[state.sort.key] || SORT_VALUE.costUsd;
+    names.sort(function (a, b) {
+      return (value(apps[a].totals) - value(apps[b].totals)) * state.sort.dir || (a < b ? -1 : a > b ? 1 : 0);
+    });
+    table.append(
+      h(
+        "thead",
+        null,
+        h(
+          "tr",
+          null,
+          h("th", null, "App"),
+          sortable("Requests", "requests"),
+          sortable("Tokens", "tokens"),
+          sortable("Cost", "costUsd"),
+          h("th", { class: "num" }, "Errors"),
+          h("th", { class: "num" }, "p95"),
+          h("th", null, "Last request"),
+        ),
+      ),
+    );
+    var body = h("tbody", null);
+    names.forEach(function (name) {
+      var t = apps[name].totals;
+      body.append(
+        h(
+          "tr",
+          null,
+          h("td", null, name),
+          h("td", { class: "num" }, integer.format(t.requests)),
+          h("td", { class: "num" }, fmtCount(tokensOf(t))),
+          h("td", { class: "num" }, fmtCost(t.costUsd)),
+          h("td", { class: "num" }, integer.format(errorsOf(t))),
+          h("td", { class: "num" }, t.latency.p95Ms === null ? "n/a" : "\u2264 " + fmtMs(t.latency.p95Ms)),
+          h("td", null, fmtTime(t.lastRequestAt)),
+        ),
+      );
+    });
+    table.append(body);
+  }
+
+  function renderModels() {
+    var totals = {};
+    Object.keys(state.report.apps).forEach(function (name) {
+      var models = state.report.apps[name].models;
+      Object.keys(models).forEach(function (model) {
+        var sum = totals[model] || { requests: 0, tokens: 0, costUsd: 0 };
+        totals[model] = { requests: sum.requests + models[model].requests, tokens: sum.tokens + models[model].tokens, costUsd: sum.costUsd + models[model].costUsd };
+      });
+    });
+    var rows = Object.keys(totals)
+      .map(function (model) {
+        return { model: model, usage: totals[model] };
+      })
+      .sort(function (a, b) {
+        return b.usage.costUsd - a.usage.costUsd || b.usage.requests - a.usage.requests || (a.model < b.model ? -1 : 1);
+      });
+    var table = $("models");
+    table.replaceChildren();
+    $("models-note").textContent = rows.length > MODEL_ROWS ? "Top " + MODEL_ROWS + " of " + rows.length + " models, by cost." : rows.length === 0 ? "No model calls in this range." : "";
+    if (rows.length === 0) return;
+    table.append(h("thead", null, h("tr", null, h("th", null, "Model"), h("th", { class: "num" }, "Requests"), h("th", { class: "num" }, "Tokens"), h("th", { class: "num" }, "Cost"))));
+    var body = h("tbody", null);
+    rows.slice(0, MODEL_ROWS).forEach(function (row) {
+      body.append(
+        h(
+          "tr",
+          null,
+          h("td", { class: "wrap" }, row.model),
+          h("td", { class: "num" }, integer.format(row.usage.requests)),
+          h("td", { class: "num" }, fmtCount(row.usage.tokens)),
+          h("td", { class: "num" }, fmtCost(row.usage.costUsd)),
+        ),
+      );
+    });
+    table.append(body);
+  }
+
+  // ---------------------------------------------------------------- charts
+
+  function destroyCharts() {
+    state.charts.forEach(function (chart) {
+      chart.destroy();
+    });
+    state.charts = [];
+  }
+
+  /** One value per UTC day of the range, for every app that has records. Days without records are 0. */
+  function dailySeries(metric) {
+    var report = state.report;
+    var dates = [];
+    for (var at = Date.parse(report.from + "T00:00:00Z"); at <= Date.parse(report.to + "T00:00:00Z"); at += 86400000) {
+      dates.push(new Date(at).toISOString().slice(0, 10));
+    }
+    var names = Object.keys(report.apps).sort();
+    var series = names.map(function (name) {
+      var byDate = {};
+      report.apps[name].days.forEach(function (day) {
+        byDate[day.date] = metric(day);
+      });
+      return dates.map(function (date) {
+        return byDate[date] || 0;
+      });
+    });
+    return {
+      xs: dates.map(function (date) {
+        return Date.parse(date + "T00:00:00Z") / 1000;
+      }),
+      names: names,
+      series: series,
+    };
+  }
+
+  function renderChart(id, metric, fmt) {
+    var container = $(id);
+    container.replaceChildren();
+    var data = dailySeries(metric);
+    var hasData = data.series.some(function (values) {
+      return values.some(function (v) {
+        return v > 0;
+      });
+    });
+    if (!hasData) {
+      container.append(h("p", { class: "muted" }, "No usage in this range."));
+      return;
+    }
+    if (!window.uPlot) {
+      container.append(h("p", { class: "muted" }, "Charts need uplot.js, which did not load."));
+      return;
+    }
+    var ink = dark.matches ? "#c9d1d9" : "#3d4551";
+    var grid = dark.matches ? "#30363d" : "#e3e6ea";
+    var options = {
+      width: Math.max(260, container.clientWidth),
+      height: CHART_HEIGHT,
+      legend: { show: true },
+      scales: {
+        x: { time: true },
+        // Counts and costs start at zero, whatever the smallest value is.
+        y: {
+          range: function (u, min, max) {
+            return [0, max > 0 ? max * 1.1 : 1];
+          },
+        },
+      },
+      axes: [
+        { stroke: ink, grid: { stroke: grid }, ticks: { stroke: grid } },
+        {
+          stroke: ink,
+          grid: { stroke: grid },
+          ticks: { stroke: grid },
+          values: function (u, splits) {
+            return splits.map(function (v) {
+              return fmt(v);
+            });
+          },
+        },
+      ],
+      series: [
+        {},
+        ...data.names.map(function (name, i) {
+          return {
+            label: name,
+            stroke: COLORS[i % COLORS.length],
+            width: 2,
+            points: { show: true, size: 5 },
+            value: function (u, v) {
+              return v === null || v === undefined ? "" : fmt(v);
+            },
+          };
+        }),
+      ],
+    };
+    var plot = new window.uPlot(options, [data.xs].concat(data.series), container);
+    state.charts.push(plot);
+  }
+
+  function renderCharts() {
+    destroyCharts();
+    renderChart("chart-requests", function (day) {
+      return day.requests;
+    }, function (v) {
+      return fmtCount(v);
+    });
+    renderChart("chart-cost", function (day) {
+      return day.costUsd;
+    }, function (v) {
+      return v >= 1 ? dollars.format(v) : "$" + v.toFixed(3);
+    });
+    renderChart("chart-tokens", tokensOf, function (v) {
+      return fmtCount(v);
+    });
+  }
+
+  function resizeCharts() {
+    state.charts.forEach(function (chart) {
+      var container = chart.root.parentNode;
+      chart.setSize({ width: Math.max(260, container.clientWidth), height: CHART_HEIGHT });
+    });
+  }
+
+  // ---------------------------------------------------------------- events
+
+  $("key-form").addEventListener("submit", function (event) {
+    event.preventDefault();
+    sessionStorage.setItem(KEY_STORAGE, $("key").value.trim());
+    $("key").value = "";
+    load();
+  });
+
+  Array.prototype.forEach.call(document.querySelectorAll("[data-days]"), function (button) {
+    button.addEventListener("click", function () {
+      state.days = Number(button.getAttribute("data-days"));
+      load();
+    });
+  });
+
+  $("refresh").addEventListener("click", function () {
+    load();
+  });
+
+  $("sign-out").addEventListener("click", function () {
+    sessionStorage.removeItem(KEY_STORAGE);
+    showSignIn("");
+  });
+
+  $("apps").addEventListener("click", function (event) {
+    var button = event.target.closest("button[data-sort]");
+    if (!button || !state.report) return;
+    var key = button.getAttribute("data-sort");
+    state.sort = { key: key, dir: state.sort.key === key ? -state.sort.dir : -1 };
+    renderApps();
+  });
+
+  dark.addEventListener("change", function () {
+    if (state.report) {
+      renderTotals();
+      renderCharts();
+    }
+  });
+
+  var resizeTimer = null;
+  window.addEventListener("resize", function () {
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(resizeCharts, 150);
+  });
+
+  load();
+})();

package/src/dashboard/assets.ts

@@ -0,0 +1,72 @@
+/**
+ * Serves the usage dashboard (`src/dashboard/page.ts`): the page, the page's own script and
+ * stylesheet, and uPlot's browser build and stylesheet from its npm package. Files are read on the
+ * first request and kept in memory. Setup does no filesystem work (I3). The bytes never change
+ * while plugboard runs, so the ETag is their hash and a revalidation answers 304.
+ */
+import { createHash } from "node:crypto"
+import { readFile } from "node:fs/promises"
+import type { IncomingMessage, ServerResponse } from "node:http"
+import { createRequire } from "node:module"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { sendText } from "../discovery.js"
+import { DASHBOARD_HEADERS, DASHBOARD_PAGE } from "./page.js"
+
+const PAGE_PREFIX = "GET /dashboard/"
+const here = dirname(fileURLToPath(import.meta.url))
+const resolveFrom = createRequire(import.meta.url)
+
+interface AssetFile {
+  readonly path: () => string
+  readonly contentType: string
+}
+
+/** The asset named by the last segment of `/dashboard/<name>`. */
+const ASSETS: Readonly<Record<string, AssetFile>> = {
+  "app.js": { path: () => join(here, "app.js"), contentType: "text/javascript; charset=utf-8" },
+  "app.css": { path: () => join(here, "app.css"), contentType: "text/css; charset=utf-8" },
+  "uplot.js": { path: () => resolveFrom.resolve("uplot/dist/uPlot.iife.min.js"), contentType: "text/javascript; charset=utf-8" },
+  "uplot.css": { path: () => resolveFrom.resolve("uplot/dist/uPlot.min.css"), contentType: "text/css; charset=utf-8" },
+}
+
+interface Asset {
+  readonly body: string
+  readonly contentType: string
+  readonly etag: string
+}
+
+const loaded = new Map<string, Promise<Asset>>()
+
+async function load(name: string): Promise<Asset> {
+  const file = ASSETS[name]
+  if (!file) throw new Error(`no dashboard asset ${name}`)
+  const body = await readFile(file.path(), "utf8")
+  const digest = createHash("sha256").update(body).digest("hex").slice(0, 32)
+  return { body, contentType: file.contentType, etag: `"${digest}"` }
+}
+
+/** The asset's bytes, read once per process. A failed read is not kept, so the next request tries again. */
+function asset(name: string): Promise<Asset> {
+  let pending = loaded.get(name)
+  if (!pending) {
+    pending = load(name)
+    loaded.set(name, pending)
+    pending.catch(() => loaded.delete(name))
+  }
+  return pending
+}
+
+/** Answers one dashboard route (`DASHBOARD_ROUTES`, already matched by the caller). */
+export async function serveDashboard(request: IncomingMessage, response: ServerResponse, route: string): Promise<void> {
+  if (route === "GET /dashboard") return sendText(response, 200, "text/html; charset=utf-8", DASHBOARD_PAGE, DASHBOARD_HEADERS)
+  const found = await asset(route.slice(PAGE_PREFIX.length))
+  // Assets revalidate on every use: a plugboard upgrade changes them, and the ETag makes that check free.
+  const headers = { ...DASHBOARD_HEADERS, "cache-control": "no-cache", etag: found.etag }
+  if (request.headers["if-none-match"] === found.etag) {
+    if (!response.headersSent && !response.destroyed) response.writeHead(304, headers)
+    response.end()
+    return
+  }
+  return sendText(response, 200, found.contentType, found.body, headers)
+}

package/src/dashboard/page.ts

@@ -0,0 +1,87 @@
+/**
+ * The usage dashboard page (`GET /dashboard`, #141): static HTML, its headers and the routes that
+ * serve it. The page holds no data. It asks for a key, then reads `GET /v1/usage` from the same
+ * origin with that key (the data never reaches the page's HTML). No inline script or style: the
+ * script and stylesheets are plugboard's own files under `/dashboard/`, served by `src/dashboard/assets.ts`.
+ */
+
+/** Scripts and styles from this origin only; nothing else may load, frame or submit. */
+export const DASHBOARD_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'"
+
+/** Headers of every dashboard response; the assets get them too. */
+export const DASHBOARD_HEADERS: Readonly<Record<string, string>> = {
+  "content-security-policy": DASHBOARD_CSP,
+  "x-frame-options": "DENY",
+  "referrer-policy": "no-referrer",
+}
+
+/** Routes of the dashboard: the page and its four files. Served only when option `usage` is on. */
+export const DASHBOARD_ROUTES: ReadonlySet<string> = new Set([
+  "GET /dashboard",
+  "GET /dashboard/app.js",
+  "GET /dashboard/app.css",
+  "GET /dashboard/uplot.js",
+  "GET /dashboard/uplot.css",
+])
+
+export const DASHBOARD_PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="referrer" content="no-referrer">
+<title>plugboard usage</title>
+<link rel="stylesheet" href="/dashboard/uplot.css">
+<link rel="stylesheet" href="/dashboard/app.css">
+<script src="/dashboard/uplot.js" defer></script>
+<script src="/dashboard/app.js" defer></script>
+</head>
+<body>
+<header class="top">
+<h1>plugboard usage</h1>
+<p class="muted">Requests, tokens and estimated cost per app, per UTC day. Cost uses the catalog's list prices.</p>
+</header>
+<main>
+<section id="signin" class="card" hidden>
+<form id="key-form">
+<label for="key">API key</label>
+<div class="row">
+<input id="key" name="key" type="password" autocomplete="off" autocapitalize="off" spellcheck="false">
+<button type="submit" class="primary">Show usage</button>
+</div>
+<p class="muted">The admin key shows every app. An app key shows only its own. The key is kept in this tab's session storage and sent only to this server.</p>
+</form>
+<p id="auth-error" class="error" role="alert" hidden></p>
+</section>
+<section id="panel" hidden>
+<div class="toolbar">
+<div class="ranges" role="group" aria-label="Range">
+<button type="button" data-days="1">Today</button>
+<button type="button" data-days="7">7 days</button>
+<button type="button" data-days="30">30 days</button>
+<button type="button" data-days="90">90 days</button>
+</div>
+<div class="row">
+<button type="button" id="refresh">Refresh</button>
+<button type="button" id="sign-out">Sign out</button>
+</div>
+</div>
+<p id="status" class="muted" aria-live="polite"></p>
+<h2>Totals</h2>
+<div id="totals" class="cards"></div>
+<h2>Apps</h2>
+<div class="scroll"><table id="apps"></table></div>
+<h2>Requests per day</h2>
+<div id="chart-requests" class="chart"></div>
+<h2>Estimated cost per day (USD)</h2>
+<div id="chart-cost" class="chart"></div>
+<h2>Tokens per day</h2>
+<div id="chart-tokens" class="chart"></div>
+<h2>Models</h2>
+<p id="models-note" class="muted"></p>
+<div class="scroll"><table id="models"></table></div>
+</section>
+</main>
+</body>
+</html>
+`

package/src/discovery.ts

@@ -61,7 +61,7 @@ export interface Endpoint {
 /**
  * Every endpoint plugboard serves, in the order the document lists them. Dispatch lives in
  * `src/openai/route.ts` and the front-end routes; `test/http/discovery.test.ts` probes each served
- * route and fails when this list omits one (#136). `/v1/usage` and `/metrics` are added only when their options are on.
+ * route and fails when this list omits one (#136). `/v1/usage`, `/dashboard` and `/metrics` are added only when their options are on.
  */
 export const ENDPOINTS: ReadonlyArray<Endpoint> = [
   { method: "GET", path: "/", auth: false, description: "This page." },
@@ -85,7 +85,12 @@ export const ENDPOINTS: ReadonlyArray<Endpoint> = [
 function endpoints(options: PlugboardOptions): ReadonlyArray<Endpoint> {
   return [
     ...ENDPOINTS,
-    ...(options.usage.enabled ? [{ method: "GET", path: "/v1/usage", auth: true, description: "Per-app usage by day: requests, tokens, cost, latency. The admin key reads every app." }] : []),
+    ...(options.usage.enabled
+      ? [
+          { method: "GET", path: "/v1/usage", auth: true, description: "Per-app usage by day: requests, tokens, cost, latency. The admin key reads every app." },
+          { method: "GET", path: "/dashboard", auth: false, description: "Usage dashboard page. Its data needs a key (`/v1/usage`)." },
+        ]
+      : []),
     ...(options.metrics ? [{ method: "GET", path: "/metrics", auth: true, description: "Prometheus metrics." }] : []),
   ]
 }
@@ -238,6 +243,7 @@ export function renderDiscoveryHtml(doc: Discovery): string {
     const more = doc.catalog.moreProviders ? `<p>${escapeHtml(doc.catalog.moreProviders)} more providers not listed.</p>` : ""
     sections.push(`<h2>Catalog</h2><table><tr><th>Provider</th><th>Models</th><th>Examples</th></tr>${rows}</table>${more}`)
   }
+  if (doc.endpoints.some((endpoint) => endpoint.path === "/dashboard")) sections.push(`<p><a href="/dashboard">Usage dashboard</a></p>`)
   sections.push(`<h2>Try it</h2>${pre(doc.example.curl)}`)
   sections.push(
     `<h2>Endpoints</h2><table><tr><th>Method</th><th>Path</th><th>Key</th><th></th></tr>${doc.endpoints

package/src/openai/route.ts

@@ -3,7 +3,8 @@
  * `POST /v1/chat/completions` (`n` > 1 through `./fanout.ts`), and the dispatch of `POST /v1/responses`
  * and `POST /v1/completions` to `src/responses/route.ts` and `src/completions/route.ts`.
  * Observability and first-run routes (`src/discovery.ts`, `src/metrics.ts`): `GET /` and `GET /v1`
- * (keyless discovery), the authenticated `GET /v1/status`, and `GET /metrics` (option `metrics`).
+ * (keyless discovery), the authenticated `GET /v1/status`, `GET /metrics` (option `metrics`), and the
+ * usage dashboard `GET /dashboard` with its assets (option `usage`, `src/dashboard/`).
  *
  * The flow is: establish cancellation and the deadline, check origin, authenticate, parse, resolve
  * the model, call the ModelCaller, encode. Parsing, policy and encoding are imported directly;
@@ -50,6 +51,8 @@ import { serveCompletions } from "../completions/route.js"
 import { serveResponses } from "../responses/route.js"
 import { liveOptions, processMetrics, processStatus, type RuntimeStatus } from "../runtime.js"
 import type { UsageRecorder } from "../usage.js"
+import { DASHBOARD_ROUTES } from "../dashboard/page.js"
+import { serveDashboard } from "../dashboard/assets.js"
 import { chatCodec, serveChoices } from "./fanout.js"
 import { parseChatRequest } from "./request.js"
 import { collectCompletion, encodeError, encodeModelList, streamCompletion } from "./response.js"
@@ -120,7 +123,10 @@ export function createOpenAiRoute(routeHost: RouteHost) {
   const host: RouteHost = metrics ? { ...routeHost, caller: metered(routeHost.caller, metrics) } : routeHost
   /** Routes with a handler of their own. `GET /metrics` exists only when enabled; otherwise it is an unknown path. */
   const known = (route: string) =>
-    KNOWN_ROUTES.includes(route) || DISCOVERY_ROUTES.includes(route) || (metrics !== undefined && route === "GET /metrics") || (host.usage !== undefined && route === "GET /v1/usage")
+    KNOWN_ROUTES.includes(route) ||
+    DISCOVERY_ROUTES.includes(route) ||
+    (metrics !== undefined && route === "GET /metrics") ||
+    (host.usage !== undefined && (route === "GET /v1/usage" || DASHBOARD_ROUTES.has(route)))
   /** Responses to Gemini routes: errors there use Google's body. */
   const googleErrors = new WeakSet<ServerResponse>()
   const fail = (response: ServerResponse, error: PlugError, close = false) =>
@@ -176,6 +182,9 @@ export function createOpenAiRoute(routeHost: RouteHost) {
       return sendText(response, 200, "text/html; charset=utf-8", renderDiscoveryHtml(doc), PAGE_HEADERS)
     }
 
+    // The usage dashboard (#141): a page and its files, keyless like the discovery pages. Its data comes from `GET /v1/usage`, behind a key.
+    if (host.usage && DASHBOARD_ROUTES.has(route)) return serveDashboard(request, response, route)
+
     // Usage has its own credentials: the admin key reads every app, any other key only its own app (`authenticateUsage`).
     if (route === "GET /v1/usage" && host.usage) return serveUsage(request, response, url, host.usage, info)