@askalf/dario 6.8.11 → 6.8.12

package/README.md

@@ -407,7 +407,9 @@ The rolling window forgets on every restart; the **ledger** does not. Since 6.6
     Today $48.20 · Last 7d $413 · Last 30d $413
 ```
 
-Only served requests count. Traffic that was metered anyway — an API key upstream, or Anthropic's paid `extra_usage` overage — is kept in its own column and reported as spent, not saved. `dario usage --card` writes the headline as a 640×320 SVG you can drop in a README or a post; `--no-ledger` / `DARIO_LEDGER=0` turns the file off, `DARIO_LEDGER_PATH` moves it, and `GET /analytics/ledger` is the per-day table behind the number. Details: [api-equivalent-spend.md](./docs/api-equivalent-spend.md).
+Only served requests count. Traffic that was metered anyway — an API key upstream, or Anthropic's paid `extra_usage` overage — is kept in its own column and reported as spent, not saved. `dario usage --card` writes the headline as a 640×320 SVG you can drop in a README or a post, and `--donut` writes the same number as three rings — by model, by key, subscription vs metered; `--no-ledger` / `DARIO_LEDGER=0` turns the file off, `DARIO_LEDGER_PATH` moves it, and `GET /analytics/ledger` is the per-day table behind the number. Details: [api-equivalent-spend.md](./docs/api-equivalent-spend.md).
+
+**Scrape it, or open it.** `GET /metrics` is the same state as Prometheus text exposition — window, seats, models, consumers, queue, latency quantiles, burn rates, ledger — so Grafana reads dario like anything else. `GET /analytics/ui` is a self-contained dashboard page with the headline, the rings and the tables, refreshing every minute. Both sit behind the same gate as `/analytics`; `--analytics-token` (env `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on those paths and nowhere else, so a scraper or a browser can hold the numbers without holding request rights. Families and the gate: [analytics.md](./docs/analytics.md).
 
 ## It tracks a moving target
 

package/dist/cli.d.ts

@@ -10,6 +10,14 @@
  *   dario logout    — Remove saved credentials
  */
 import { type EffortValue } from './cc-template.js';
+/**
+ * Bare words after `proxy` (dario#1353). `dario proxy` takes flags only, but it
+ * read them by prefix and ignored everything else, so `dario proxy status`,
+ * typed by someone expecting a report, started a full proxy and ran the OAuth
+ * refresh timer against the shared credential for five days. Anything that is
+ * not a flag is an error now; the one obvious guess is an alias for the report.
+ */
+export declare function strayProxyArgs(argv: readonly string[]): string[];
 /**
  * Parse `--system-prompt=<verbatim|partial|aggressive|filepath>` (or the
  * `DARIO_SYSTEM_PROMPT` env-var fallback) into the value passed through

package/dist/cli.js

@@ -18,6 +18,7 @@
 // other startup side effect.
 import { unlink, writeFile } from 'node:fs/promises';
 import { formatLedgerSummary, formatLedgerConsumers, formatUsd, renderLedgerCard, readLedgerFile, resolveLedgerPath, summarizeLedger } from './ledger.js';
+import { renderSpendDonuts } from './donuts.js';
 import { KeyStore, createKey, revokeKey, rotateKey, deleteKey, parseExpiry, publicKey, resolveKeysPath, KEY_NAME_RE } from './keys.js';
 import { loadAllAccounts as loadAllAccountsForIdentity, regenerateClientIdentity } from './accounts.js';
 import { maskEmail, parsePoolHeadroomFloor } from './pool.js';
@@ -299,7 +300,28 @@ async function logout() {
         }
     }
 }
+/**
+ * Bare words after `proxy` (dario#1353). `dario proxy` takes flags only, but it
+ * read them by prefix and ignored everything else, so `dario proxy status`,
+ * typed by someone expecting a report, started a full proxy and ran the OAuth
+ * refresh timer against the shared credential for five days. Anything that is
+ * not a flag is an error now; the one obvious guess is an alias for the report.
+ */
+export function strayProxyArgs(argv) {
+    // The command token is the first `proxy`, wherever it sits: `--no-tui` is a
+    // global flag that may precede it (review on dario#1353). A second bare
+    // `proxy` is a stray word like any other.
+    const command = argv.indexOf('proxy');
+    return argv.filter((a, i) => i !== command && !a.startsWith('-'));
+}
 async function proxy() {
+    const stray = strayProxyArgs(args);
+    if (stray.length === 1 && stray[0] === 'status')
+        return status();
+    if (stray.length > 0) {
+        console.error(`[dario] Unknown proxy argument "${stray[0]}". \`dario proxy\` takes flags only (--port=, --host=, ...); nothing was started. For a report run \`dario status\`.`);
+        process.exit(1);
+    }
     // v4: load ~/.dario/config.json once at startup so file-stored values
     // serve as defaults below where no CLI flag / env var supplies one.
     // Precedence per M1: defaults < file < env < CLI. Missing-file is
@@ -372,6 +394,10 @@ async function proxy() {
     // proxies). Stops dario rotating a shared refresh token out from under an
     // interactive Claude Code on the same machine.
     const noClaudeAuth = args.includes('--no-claude-auth');
+    // Read-only token for /analytics*, /metrics and the /analytics/ui page:
+    // a scraper or a browser gets the numbers, never a request slot.
+    const analyticsTokenArg = args.find(a => a.startsWith('--analytics-token='));
+    const analyticsToken = analyticsTokenArg ? analyticsTokenArg.slice('--analytics-token='.length) : undefined;
     const modelArg = args.find(a => a.startsWith('--model='));
     const model = modelArg ? modelArg.split('=')[1] : undefined;
     // --fast-model=MODEL: route Haiku-tier (CC sub-agent) requests to this
@@ -678,7 +704,7 @@ async function proxy() {
         console.error(`[dario] Override (not recommended): pass --unsafe-no-auth if you have out-of-band network controls and accept the risk.`);
         process.exit(1);
     }
-    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath });
+    await startProxy({ port, host, verbose, verboseBodies, model, fastModel, noClaudeAuth, analyticsToken, passthrough, preserveTools, hybridTools, mergeTools, noAutoDetect, strictTls, pacingMinMs, pacingJitterMs, thinkTimeBaseMs, thinkTimePerTokenMs, thinkTimeJitterMs, thinkTimeMaxMs, sessionStartMinMs, sessionStartJitterMs, stealth, drainOnClose, sessionIdleRotateMs, sessionRotateJitterMs, sessionMaxAgeMs, sessionPerClient, preserveOrchestrationTags, noLiveCapture, strictTemplate, maxConcurrent, maxQueued, queueTimeoutMs, maxConcurrentPerConsumer, poolStrategy, poolHeadroomFloor, poolSharedState, poolSharedStateIntervalMs, effort, maxTokens, poolFallbackModel, modelAliases, logFile, passthroughBetas, skipFields, systemPrompt, overageGuardEnabled, overageGuardBehavior, overageGuardCooldownMs, overageGuardNotifyOs, honorClientThinking, preserveOutputFormat, midstreamContinue, ledger, keys, keysPath });
 }
 /**
  * `dario keys` — named keys for a shared dario (v6.8, dario#1318). One
@@ -1716,7 +1742,9 @@ async function help() {
                              existing credentials and runs a fresh OAuth
                              flow — for when the refresh token is dead and
                              /health still reports access-token countdown.
-    dario proxy [options]    Start the API proxy server
+    dario proxy [options]    Start the API proxy server. Flags only: a bare
+                             word after "proxy" is an error, and "dario proxy
+                             status" prints the report instead of starting.
     dario status             Check authentication status
     dario refresh            Force token refresh
     dario resume             Clear the overage-guard halt on a running proxy.
@@ -1851,6 +1879,9 @@ async function help() {
                              down). --card[=file.svg] writes a share
                              card of that number (default
                              dario-api-equivalent.svg). (v6.6)
+                             --donut[=file.svg] writes it as three
+                             rings: by model, by key, subscription
+                             vs metered (default dario-spend-donuts.svg).
                              --by-key splits the lifetime number per
                              consumer: named key, x-dario-consumer
                              header, or hashed user id. (v6.8)
@@ -1876,6 +1907,11 @@ async function help() {
                              instead of --model, so Claude Code's cheap
                              sub-agents aren't upgraded to the forced model.
                              Same MODEL forms as --model. No effect unless set.
+    --analytics-token=TOKEN  Read-only credential for /analytics*, /metrics and
+                             the /analytics/ui page (env DARIO_ANALYTICS_TOKEN).
+                             Refused on /v1/*, /accounts, /status, /admin/*:
+                             a scraper or a browser gets the numbers, never
+                             a request slot. Gates nothing without DARIO_API_KEY.
     --no-claude-auth         Don't load or refresh the Claude OAuth token —
                              for OpenAI-only proxies (e.g. --model=openai:...).
                              Prevents dario rotating a shared refresh token out
@@ -2672,6 +2708,18 @@ async function usage() {
         if (!asJson)
             console.log(`  Wrote ${cardPath} — ${formatUsd(lifetime.apiEquivalentCost)} API-equivalent since ${lifetime.since.slice(0, 10)}.`);
     }
+    // --donut / --donut=<file>: the three spend rings (by model, by key, by billing).
+    const donutArg = args.find(a => a === '--donut' || a.startsWith('--donut='));
+    const donutPath = donutArg ? (donutArg.includes('=') ? donutArg.slice('--donut='.length) : 'dario-spend-donuts.svg') : null;
+    if (donutPath) {
+        if (!lifetime) {
+            console.error(`  No lifetime numbers to draw${lifetimeNote ? ` (${lifetimeNote})` : ''}.`);
+            process.exit(1);
+        }
+        await writeFile(donutPath, renderSpendDonuts(lifetime), 'utf8');
+        if (!asJson)
+            console.log(`  Wrote ${donutPath} — spend by model, by key and by billing since ${lifetime.since.slice(0, 10)}.`);
+    }
     if (asJson) {
         if (payload) {
             process.stdout.write(JSON.stringify(payload, null, 2) + '\n');

package/dist/donuts.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Spend donuts — where the API-equivalent number comes from, as shares.
+ *
+ * Three rings from the ledger, no new data: by model, by consumer (named
+ * key / `x-dario-consumer`), and covered-vs-metered. Rendered as one SVG
+ * (`dario usage --donut`, `GET /analytics/donuts.svg`) and inside the
+ * server-rendered `/analytics/view` fragment that the `/analytics/ui` shell
+ * page loads. Same palette and frame as the share card in ledger.ts.
+ *
+ * Pure over a LedgerSummary / AnalyticsSummary so the geometry is testable
+ * without a proxy.
+ */
+import type { LedgerSummary } from './ledger.js';
+import type { AnalyticsSummary } from './analytics.js';
+import type { QueueSnapshot } from './request-queue.js';
+/** What /analytics serves: the summary plus the queue snapshot riding along. */
+export type AnalyticsView = AnalyticsSummary & {
+    queue?: QueueSnapshot;
+};
+export interface DonutSlice {
+    label: string;
+    value: number;
+    share: number;
+}
+export declare const escapeHtml: (s: string) => string;
+/**
+ * Top `max` entries by value plus one "other" bucket; zero and negative
+ * values are dropped. Shares sum to 1 (or the array is empty).
+ */
+export declare function donutSlices(entries: Record<string, number>, max?: number): DonutSlice[];
+/** One ring of arcs. A single slice is drawn as a full circle (an arc from a point to itself is empty). */
+export declare function donutPaths(slices: readonly DonutSlice[], cx: number, cy: number, r: number, width: number): string;
+/** The three-ring SVG. 640×320, the share card's frame. */
+export declare function renderSpendDonuts(s: LedgerSummary): string;
+/**
+ * The server-rendered fragment behind `/analytics/ui`: headline, the three
+ * rings, the rolling window, and a per-model table. Same gate as
+ * `/analytics`; the shell page fetches it with the token the viewer typed.
+ */
+export declare function renderAnalyticsView(summary: AnalyticsView, lifetime: LedgerSummary | null, version: string): string;
+/**
+ * The static shell for `/analytics/ui`. Carries NO data — it is safe to
+ * serve without auth — and asks the viewer for the token once (kept in
+ * sessionStorage), then fetches `/analytics/view` every 60 s with it.
+ */
+export declare const ANALYTICS_UI_SHELL = "<!doctype html>\n<html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n<title>dario analytics</title>\n<style>\n  :root{color-scheme:dark}\n  body{margin:0;background:#0a0a0f;color:#e5e7eb;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,\"Liberation Mono\",monospace;font-size:14px}\n  header{display:flex;gap:12px;align-items:center;padding:14px 20px;border-bottom:1px solid #1f2937;background:linear-gradient(90deg,#7c3aed,#db2777) top/100% 4px no-repeat,#0a0a0f}\n  header h1{font-size:14px;letter-spacing:2px;margin:0;color:#9ca3af;font-weight:600}\n  header input{background:#111827;color:#e5e7eb;border:1px solid #374151;border-radius:6px;padding:6px 10px;font:inherit;width:22em}\n  header button{background:#7c3aed;color:#fff;border:0;border-radius:6px;padding:6px 12px;font:inherit;cursor:pointer}\n  #status{color:#9ca3af;margin-left:auto}\n  main{padding:20px;max-width:1100px;margin:0 auto}\n  .headline{font-size:34px;font-weight:700;color:#fff;margin:6px 0 16px}\n  .headline span{display:block;font-size:13px;font-weight:400;color:#9ca3af;margin-top:4px}\n  .headline.muted{color:#6b7280}\n  .stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin-bottom:18px}\n  .stat{background:#111827;border:1px solid #1f2937;border-radius:12px;padding:12px 14px}\n  .stat .v{font-size:20px;font-weight:700;color:#fff}.stat .l{font-size:11px;color:#9ca3af;margin-top:2px}\n  .rings svg{width:100%;max-width:640px;height:auto;display:block;margin:0 auto 18px}\n  table{width:100%;border-collapse:collapse;margin:0 0 18px;font-size:12px}\n  th,td{text-align:right;padding:6px 8px;border-bottom:1px solid #1f2937}th:first-child,td:first-child{text-align:left}\n  th{color:#9ca3af;font-weight:500}\n  .foot{color:#6b7280;font-size:11px}\n  .err{color:#fca5a5;padding:20px;background:#1f1115;border:1px solid #7f1d1d;border-radius:12px}\n</style></head>\n<body>\n<header><h1>DARIO ANALYTICS</h1>\n  <input id=\"tok\" type=\"password\" placeholder=\"analytics token or API key (blank on an unkeyed proxy)\" autocomplete=\"off\">\n  <button id=\"go\">connect</button><span id=\"status\"></span></header>\n<main id=\"view\"></main>\n<script>\n(function(){\n  var tok=document.getElementById('tok'),view=document.getElementById('view'),status=document.getElementById('status'),timer=null;\n  try{tok.value=sessionStorage.getItem('dario.analytics.token')||''}catch(e){}\n  function headers(){var h={};if(tok.value)h['Authorization']='Bearer '+tok.value;return h}\n  function load(){\n    fetch('/analytics/view',{headers:headers(),cache:'no-store'}).then(function(r){\n      if(r.status===401){view.innerHTML='<div class=\"err\">401 \u2014 this proxy is keyed. Paste its analytics token (DARIO_ANALYTICS_TOKEN) or API key above.</div>';status.textContent='';return}\n      if(!r.ok){view.innerHTML='<div class=\"err\">'+r.status+' from /analytics/view</div>';return}\n      return r.text().then(function(html){view.innerHTML=html;status.textContent='live \u00B7 refreshes every 60 s';try{sessionStorage.setItem('dario.analytics.token',tok.value)}catch(e){}})\n    }).catch(function(e){view.innerHTML='<div class=\"err\">'+String(e)+'</div>'});\n  }\n  function start(){if(timer)clearInterval(timer);load();timer=setInterval(load,60000)}\n  document.getElementById('go').addEventListener('click',start);\n  tok.addEventListener('keydown',function(e){if(e.key==='Enter')start()});\n  start();\n})();\n</script>\n</body></html>\n";

package/dist/donuts.js

@@ -0,0 +1,176 @@
+import { formatUsd } from './ledger.js';
+const PALETTE = ['#7c3aed', '#db2777', '#2563eb', '#059669', '#d97706', '#0891b2'];
+const OTHER = '#6b7280';
+export const escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+/**
+ * Top `max` entries by value plus one "other" bucket; zero and negative
+ * values are dropped. Shares sum to 1 (or the array is empty).
+ */
+export function donutSlices(entries, max = 5) {
+    const rows = Object.entries(entries).filter(([, v]) => Number.isFinite(v) && v > 0).sort((a, b) => b[1] - a[1]);
+    const total = rows.reduce((n, [, v]) => n + v, 0);
+    if (total <= 0)
+        return [];
+    const head = rows.slice(0, max);
+    const rest = rows.slice(max).reduce((n, [, v]) => n + v, 0);
+    const slices = head.map(([label, value]) => ({ label, value, share: value / total }));
+    if (rest > 0)
+        slices.push({ label: 'other', value: rest, share: rest / total });
+    return slices;
+}
+const polar = (cx, cy, r, angle) => [cx + r * Math.cos(angle), cy + r * Math.sin(angle)];
+/** One ring of arcs. A single slice is drawn as a full circle (an arc from a point to itself is empty). */
+export function donutPaths(slices, cx, cy, r, width) {
+    if (slices.length === 0)
+        return `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="#1f2937" stroke-width="${width}"/>`;
+    if (slices.length === 1)
+        return `<circle cx="${cx}" cy="${cy}" r="${r}" fill="none" stroke="${PALETTE[0]}" stroke-width="${width}"/>`;
+    let start = -Math.PI / 2;
+    const out = [];
+    slices.forEach((s, i) => {
+        const sweep = s.share * 2 * Math.PI;
+        const end = start + sweep;
+        const [x1, y1] = polar(cx, cy, r, start);
+        const [x2, y2] = polar(cx, cy, r, end);
+        const large = sweep > Math.PI ? 1 : 0;
+        const color = s.label === 'other' ? OTHER : PALETTE[i % PALETTE.length];
+        out.push(`<path d="M ${x1.toFixed(2)} ${y1.toFixed(2)} A ${r} ${r} 0 ${large} 1 ${x2.toFixed(2)} ${y2.toFixed(2)}" fill="none" stroke="${color}" stroke-width="${width}"/>`);
+        start = end;
+    });
+    return out.join('\n    ');
+}
+const pct = (share) => `${Math.round(share * 100)}%`;
+function ring(title, slices, cx, empty) {
+    const cy = 150;
+    const r = 62;
+    const width = 22;
+    const legend = slices.slice(0, 6).map((s, i) => {
+        const color = s.label === 'other' ? OTHER : PALETTE[i % PALETTE.length];
+        const y = 236 + i * 15;
+        const label = s.label.length > 18 ? s.label.slice(0, 17) + '…' : s.label;
+        return `<rect x="${cx - 95}" y="${y - 9}" width="9" height="9" rx="2" fill="${color}"/>` +
+            `<text x="${cx - 80}" y="${y}" font-size="11" fill="#d1d5db">${escapeHtml(label)}</text>` +
+            `<text x="${cx + 95}" y="${y}" font-size="11" fill="#9ca3af" text-anchor="end">${escapeHtml(formatUsd(s.value))} · ${pct(s.share)}</text>`;
+    }).join('\n    ');
+    const centre = slices.length === 0
+        ? `<text x="${cx}" y="${cy + 4}" font-size="11" fill="#6b7280" text-anchor="middle">${escapeHtml(empty)}</text>`
+        : `<text x="${cx}" y="${cy + 5}" font-size="13" font-weight="700" fill="#ffffff" text-anchor="middle">${escapeHtml(formatUsd(slices.reduce((n, s) => n + s.value, 0)))}</text>`;
+    return `<text x="${cx}" y="58" font-size="12" fill="#9ca3af" text-anchor="middle" letter-spacing="1.5">${escapeHtml(title.toUpperCase())}</text>
+    ${donutPaths(slices, cx, cy, r, width)}
+    ${centre}
+    ${legend}`;
+}
+/** The three-ring SVG. 640×320, the share card's frame. */
+export function renderSpendDonuts(s) {
+    const byModel = donutSlices(Object.fromEntries(Object.entries(s.perModel).map(([m, v]) => [m, v.apiEquivalentCost + v.meteredCost])));
+    const byConsumer = donutSlices(Object.fromEntries(Object.entries(s.perConsumer).map(([c, v]) => [c, v.apiEquivalentCost + v.meteredCost])));
+    // Short on purpose: the legend column is 18 characters wide.
+    const byBilling = donutSlices({ 'subscription': s.apiEquivalentCost, 'metered': s.meteredCost });
+    const total = formatUsd(s.apiEquivalentCost + s.meteredCost);
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="320" viewBox="0 0 640 320" role="img" aria-label="${escapeHtml(total)} of spend through dario, by model, by key and by billing">
+  <defs>
+    <linearGradient id="accent" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#7c3aed"/>
+      <stop offset="1" stop-color="#db2777"/>
+    </linearGradient>
+    <clipPath id="card"><rect width="640" height="320" rx="20"/></clipPath>
+  </defs>
+  <rect width="640" height="320" rx="20" fill="#0a0a0f"/>
+  <rect x="0" y="0" width="640" height="6" fill="url(#accent)" clip-path="url(#card)"/>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace" fill="#e5e7eb">
+    <text x="40" y="34" font-size="12" fill="#9ca3af" letter-spacing="2">SPEND THROUGH DARIO · ${escapeHtml(total)} · since ${escapeHtml(s.since.slice(0, 10))}</text>
+    ${ring('by model', byModel, 112, 'no traffic yet')}
+    ${ring('by key', byConsumer, 320, 'no named keys')}
+    ${ring('by billing', byBilling, 528, 'no traffic yet')}
+    <text x="600" y="308" font-size="11" fill="#6b7280" text-anchor="end">dario</text>
+  </g>
+</svg>
+`;
+}
+/**
+ * The server-rendered fragment behind `/analytics/ui`: headline, the three
+ * rings, the rolling window, and a per-model table. Same gate as
+ * `/analytics`; the shell page fetches it with the token the viewer typed.
+ */
+export function renderAnalyticsView(summary, lifetime, version) {
+    const w = summary.window;
+    const stat = (label, value) => `<div class="stat"><div class="v">${escapeHtml(value)}</div><div class="l">${escapeHtml(label)}</div></div>`;
+    const headline = lifetime
+        ? `<div class="headline">${escapeHtml(formatUsd(lifetime.apiEquivalentCost))}<span> API-equivalent · covered by subscriptions · since ${escapeHtml(lifetime.since.slice(0, 10))} · ${lifetime.requests.toLocaleString('en-US')} requests</span></div>`
+        : '<div class="headline muted">ledger disabled <span>start without --no-ledger to keep lifetime spend</span></div>';
+    const rings = lifetime ? renderSpendDonuts(lifetime) : '';
+    const models = lifetime
+        ? Object.entries(lifetime.perModel).sort((a, b) => (b[1].apiEquivalentCost + b[1].meteredCost) - (a[1].apiEquivalentCost + a[1].meteredCost))
+        : [];
+    const table = models.length
+        ? `<table><thead><tr><th>model</th><th>requests</th><th>in</th><th>out</th><th>cache read</th><th>api-equivalent</th><th>metered</th></tr></thead><tbody>${models.map(([m, v]) => `<tr><td>${escapeHtml(m)}</td><td>${v.requests.toLocaleString('en-US')}</td><td>${v.inputTokens.toLocaleString('en-US')}</td><td>${v.outputTokens.toLocaleString('en-US')}</td><td>${v.cacheReadTokens.toLocaleString('en-US')}</td><td>${escapeHtml(formatUsd(v.apiEquivalentCost))}</td><td>${escapeHtml(formatUsd(v.meteredCost))}</td></tr>`).join('')}</tbody></table>`
+        : '';
+    const accounts = Object.entries(summary.perAccount).map(([a, s]) => `<tr><td>${escapeHtml(a)}</td><td>${s.requests.toLocaleString('en-US')}</td><td>${Math.round(s.currentUtil5h * 100)}%</td><td>${Math.round(s.currentUtil7d * 100)}%</td><td>${escapeHtml(s.lastClaim)}</td></tr>`).join('');
+    return `${headline}
+<div class="stats">
+  ${stat(`requests · last ${w.minutes} min`, w.requests.toLocaleString('en-US'))}
+  ${stat('avg latency', `${Math.round(w.avgLatencyMs)} ms`)}
+  ${stat('error rate', `${(w.errorRate * 100).toFixed(1)}%`)}
+  ${stat('cached prompt', `${Math.round(w.cachedPromptPercent)}%`)}
+  ${stat('in flight / queued', `${summary.queue?.active ?? 0} / ${summary.queue?.queued ?? 0}`)}
+</div>
+<div class="rings">${rings}</div>
+${table}
+${accounts ? `<table><thead><tr><th>seat</th><th>requests</th><th>5h</th><th>7d</th><th>last claim</th></tr></thead><tbody>${accounts}</tbody></table>` : ''}
+<div class="foot">dario ${escapeHtml(version)} · rendered ${escapeHtml(new Date().toISOString().slice(0, 19).replace('T', ' '))} UTC</div>`;
+}
+/**
+ * The static shell for `/analytics/ui`. Carries NO data — it is safe to
+ * serve without auth — and asks the viewer for the token once (kept in
+ * sessionStorage), then fetches `/analytics/view` every 60 s with it.
+ */
+export const ANALYTICS_UI_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>dario analytics</title>
+<style>
+  :root{color-scheme:dark}
+  body{margin:0;background:#0a0a0f;color:#e5e7eb;font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;font-size:14px}
+  header{display:flex;gap:12px;align-items:center;padding:14px 20px;border-bottom:1px solid #1f2937;background:linear-gradient(90deg,#7c3aed,#db2777) top/100% 4px no-repeat,#0a0a0f}
+  header h1{font-size:14px;letter-spacing:2px;margin:0;color:#9ca3af;font-weight:600}
+  header input{background:#111827;color:#e5e7eb;border:1px solid #374151;border-radius:6px;padding:6px 10px;font:inherit;width:22em}
+  header button{background:#7c3aed;color:#fff;border:0;border-radius:6px;padding:6px 12px;font:inherit;cursor:pointer}
+  #status{color:#9ca3af;margin-left:auto}
+  main{padding:20px;max-width:1100px;margin:0 auto}
+  .headline{font-size:34px;font-weight:700;color:#fff;margin:6px 0 16px}
+  .headline span{display:block;font-size:13px;font-weight:400;color:#9ca3af;margin-top:4px}
+  .headline.muted{color:#6b7280}
+  .stats{display:grid;grid-template-columns:repeat(auto-fit,minmax(150px,1fr));gap:12px;margin-bottom:18px}
+  .stat{background:#111827;border:1px solid #1f2937;border-radius:12px;padding:12px 14px}
+  .stat .v{font-size:20px;font-weight:700;color:#fff}.stat .l{font-size:11px;color:#9ca3af;margin-top:2px}
+  .rings svg{width:100%;max-width:640px;height:auto;display:block;margin:0 auto 18px}
+  table{width:100%;border-collapse:collapse;margin:0 0 18px;font-size:12px}
+  th,td{text-align:right;padding:6px 8px;border-bottom:1px solid #1f2937}th:first-child,td:first-child{text-align:left}
+  th{color:#9ca3af;font-weight:500}
+  .foot{color:#6b7280;font-size:11px}
+  .err{color:#fca5a5;padding:20px;background:#1f1115;border:1px solid #7f1d1d;border-radius:12px}
+</style></head>
+<body>
+<header><h1>DARIO ANALYTICS</h1>
+  <input id="tok" type="password" placeholder="analytics token or API key (blank on an unkeyed proxy)" autocomplete="off">
+  <button id="go">connect</button><span id="status"></span></header>
+<main id="view"></main>
+<script>
+(function(){
+  var tok=document.getElementById('tok'),view=document.getElementById('view'),status=document.getElementById('status'),timer=null;
+  try{tok.value=sessionStorage.getItem('dario.analytics.token')||''}catch(e){}
+  function headers(){var h={};if(tok.value)h['Authorization']='Bearer '+tok.value;return h}
+  function load(){
+    fetch('/analytics/view',{headers:headers(),cache:'no-store'}).then(function(r){
+      if(r.status===401){view.innerHTML='<div class="err">401 — this proxy is keyed. Paste its analytics token (DARIO_ANALYTICS_TOKEN) or API key above.</div>';status.textContent='';return}
+      if(!r.ok){view.innerHTML='<div class="err">'+r.status+' from /analytics/view</div>';return}
+      return r.text().then(function(html){view.innerHTML=html;status.textContent='live · refreshes every 60 s';try{sessionStorage.setItem('dario.analytics.token',tok.value)}catch(e){}})
+    }).catch(function(e){view.innerHTML='<div class="err">'+String(e)+'</div>'});
+  }
+  function start(){if(timer)clearInterval(timer);load();timer=setInterval(load,60000)}
+  document.getElementById('go').addEventListener('click',start);
+  tok.addEventListener('keydown',function(e){if(e.key==='Enter')start()});
+  start();
+})();
+</script>
+</body></html>
+`;

package/dist/metrics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Prometheus text exposition for `GET /metrics` (dario#1341).
+ *
+ * Everything here is derived from state dario already keeps — the rolling
+ * analytics window, the request queue, and the ledger — rendered in the
+ * text format every scraper reads. No new collection, no new state: the
+ * endpoint is a view, and a scrape costs the same as `GET /analytics`.
+ *
+ * Pure over its inputs so it is testable without a proxy. Label values are
+ * escaped per the exposition rules (backslash, double quote, newline).
+ */
+import type { AnalyticsSummary, RequestRecord } from './analytics.js';
+import type { QueueSnapshot } from './request-queue.js';
+import type { LedgerSummary } from './ledger.js';
+export interface MetricsInput {
+    summary: AnalyticsSummary;
+    queue: QueueSnapshot;
+    lifetime: LedgerSummary | null;
+    /** Most recent records, newest last — the latency quantiles come from these. */
+    recent: readonly RequestRecord[];
+    version: string;
+}
+/** Nearest-rank quantile over a sorted ascending array. */
+export declare function quantile(sorted: readonly number[], q: number): number;
+export declare function renderPrometheus(input: MetricsInput): string;

package/dist/metrics.js

@@ -0,0 +1,116 @@
+import { billingBucketFromClaim } from './analytics.js';
+const escapeLabel = (v) => v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+const labels = (kv) => {
+    const parts = Object.entries(kv).map(([k, v]) => `${k}="${escapeLabel(v)}"`);
+    return parts.length ? `{${parts.join(',')}}` : '';
+};
+const num = (n) => {
+    if (!Number.isFinite(n))
+        return n === Infinity ? '+Inf' : n === -Infinity ? '-Inf' : 'NaN';
+    return String(n);
+};
+/** Nearest-rank quantile over a sorted ascending array. */
+export function quantile(sorted, q) {
+    if (sorted.length === 0)
+        return NaN;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(q * sorted.length) - 1));
+    return sorted[idx];
+}
+export function renderPrometheus(input) {
+    const { summary, queue, lifetime, recent, version } = input;
+    const out = [];
+    // `_total` names are counters by Prometheus convention; everything else here
+    // is a gauge. The latency summary is emitted by hand below.
+    const metric = (name, help, rows, type = name.endsWith('_total') ? 'counter' : 'gauge') => {
+        if (rows.length === 0)
+            return;
+        out.push(`# HELP ${name} ${help}`);
+        out.push(`# TYPE ${name} ${type}`);
+        for (const [kv, v] of rows)
+            out.push(`${name}${labels(kv)} ${num(v)}`);
+    };
+    metric('dario_info', 'dario version, always 1.', [[{ version }, 1]]);
+    // ---- all-time (since proxy start) -------------------------------------
+    const all = summary.allTime;
+    metric('dario_requests_total', 'Requests served since the proxy started.', [[{}, all.requests]]);
+    metric('dario_tokens_total', 'Tokens since the proxy started, by kind.', [
+        [{ kind: 'input' }, all.totalInputTokens],
+        [{ kind: 'output' }, all.totalOutputTokens],
+        [{ kind: 'cache_read' }, all.totalCacheReadTokens],
+        [{ kind: 'cache_create' }, all.totalCacheCreateTokens],
+        [{ kind: 'thinking' }, all.totalThinkingTokens],
+    ]);
+    metric('dario_estimated_cost_usd_total', 'API-equivalent cost of all traffic since the proxy started, USD at list price.', [[{}, all.estimatedCost]]);
+    metric('dario_error_rate', 'Share of requests that failed, 0..1, all-time.', [[{}, all.errorRate]]);
+    // ---- rolling window ----------------------------------------------------
+    const w = summary.window;
+    const win = { window_minutes: String(w.minutes) };
+    metric('dario_window_requests', 'Requests in the rolling window.', [[win, w.requests]]);
+    metric('dario_window_avg_latency_ms', 'Mean request latency in the rolling window, ms.', [[win, w.avgLatencyMs]]);
+    metric('dario_window_error_rate', 'Share of requests that failed in the rolling window, 0..1.', [[win, w.errorRate]]);
+    metric('dario_window_cached_prompt_percent', 'Share of prompt tokens served from cache in the rolling window, 0..100.', [[win, w.cachedPromptPercent]]);
+    metric('dario_window_estimated_cost_usd', 'API-equivalent cost of the rolling window, USD.', [[win, w.estimatedCost]]);
+    // ---- billing buckets (window) ------------------------------------------
+    const buckets = new Map();
+    for (const [claim, n] of Object.entries(w.claimBreakdown ?? {})) {
+        const b = billingBucketFromClaim(claim);
+        buckets.set(b, (buckets.get(b) ?? 0) + n);
+    }
+    metric('dario_window_billing_requests', 'Requests in the rolling window by billing bucket.', [...buckets.entries()].map(([bucket, n]) => [{ bucket }, n]));
+    // ---- per account -------------------------------------------------------
+    const accounts = Object.entries(summary.perAccount);
+    metric('dario_account_requests_total', 'Requests per pool seat since the proxy started.', accounts.map(([account, a]) => [{ account }, a.requests]));
+    metric('dario_account_utilization', 'Last reported rate-limit utilization per seat, 0..1.', accounts.flatMap(([account, a]) => [
+        [{ account, window: '5h' }, a.currentUtil5h],
+        [{ account, window: '7d' }, a.currentUtil7d],
+    ]));
+    metric('dario_account_estimated_cost_usd', 'API-equivalent cost per seat since the proxy started, USD.', accounts.map(([account, a]) => [{ account }, a.estimatedCost]));
+    // ---- per model ---------------------------------------------------------
+    const models = Object.entries(summary.perModel);
+    metric('dario_model_requests_total', 'Requests per model since the proxy started.', models.map(([model, m]) => [{ model }, m.requests]));
+    metric('dario_model_estimated_cost_usd', 'API-equivalent cost per model since the proxy started, USD.', models.map(([model, m]) => [{ model }, m.estimatedCost]));
+    // ---- per consumer (named key / header) ---------------------------------
+    const consumers = Object.entries(summary.perConsumer);
+    metric('dario_consumer_requests_total', 'Requests per consumer (named key or x-dario-consumer) since the proxy started.', consumers.map(([consumer, c]) => [{ consumer }, c.requests]));
+    metric('dario_consumer_estimated_cost_usd', 'API-equivalent cost per consumer since the proxy started, USD.', consumers.map(([consumer, c]) => [{ consumer }, c.estimatedCost]));
+    // ---- queue ---------------------------------------------------------------
+    metric('dario_queue_active', 'Requests in flight upstream.', [[{}, queue.active]]);
+    metric('dario_queue_queued', 'Requests waiting for a slot.', [[{}, queue.queued]]);
+    metric('dario_queue_max_concurrent', 'Configured in-flight ceiling.', [[{}, queue.maxConcurrent]]);
+    metric('dario_queue_max_queued', 'Configured queue ceiling.', [[{}, queue.maxQueued]]);
+    metric('dario_queue_stalled', '1 when slots are held but nothing is turning over, else 0.', [[{}, queue.stalledSince ? 1 : 0]]);
+    metric('dario_queue_max_wait_ms', 'Longest a request has waited for a slot since start, ms.', [[{}, queue.maxWaitMs]]);
+    metric('dario_queue_consumers_active', 'Distinct consumers with a request in flight.', [[{}, queue.consumersActive]]);
+    // ---- latency quantiles over the recent records -------------------------
+    const lat = recent.map(r => r.latencyMs).filter(n => Number.isFinite(n)).sort((a, b) => a - b);
+    if (lat.length > 0) {
+        out.push('# HELP dario_request_latency_ms Request latency over the most recent records, ms (nearest-rank quantiles).');
+        out.push('# TYPE dario_request_latency_ms summary');
+        for (const q of [0.5, 0.9, 0.99])
+            out.push(`dario_request_latency_ms{quantile="${q}"} ${num(quantile(lat, q))}`);
+        out.push(`dario_request_latency_ms_sum ${num(lat.reduce((a, b) => a + b, 0))}`);
+        out.push(`dario_request_latency_ms_count ${lat.length}`);
+    }
+    // ---- predictions -------------------------------------------------------
+    const p = summary.predictions;
+    if (p.estimatedExhaustionMinutes !== null) {
+        metric('dario_predicted_exhaustion_minutes', 'Minutes until the current seat window is predicted to exhaust at the present burn rate.', [[{}, p.estimatedExhaustionMinutes]]);
+    }
+    metric('dario_burn_tokens_per_minute', 'Token burn rate over the rolling window.', [[{}, p.tokenBurnRate]]);
+    metric('dario_burn_cost_usd_per_minute', 'API-equivalent cost burn rate over the rolling window, USD/min.', [[{}, p.costBurnRate]]);
+    // ---- ledger (survives restarts) ----------------------------------------
+    if (lifetime) {
+        metric('dario_ledger_requests_total', 'Requests in the ledger (covered + metered, 2xx), lifetime.', [[{}, lifetime.requests]]);
+        metric('dario_ledger_api_equivalent_usd', 'What subscription-covered traffic would have cost on the metered API, lifetime, USD.', [[{}, lifetime.apiEquivalentCost]]);
+        metric('dario_ledger_metered_usd', 'What metered traffic actually cost at list price, lifetime, USD.', [[{}, lifetime.meteredCost]]);
+        metric('dario_ledger_recent_api_equivalent_usd', 'API-equivalent spend over trailing UTC-day windows, USD.', [
+            [{ window: 'today' }, lifetime.recent.today],
+            [{ window: '7d' }, lifetime.recent.last7d],
+            [{ window: '30d' }, lifetime.recent.last30d],
+        ]);
+        metric('dario_ledger_model_api_equivalent_usd', 'Lifetime API-equivalent spend per model, USD.', Object.entries(lifetime.perModel).map(([model, m]) => [{ model, provider: m.provider }, m.apiEquivalentCost]));
+        metric('dario_ledger_model_requests_total', 'Lifetime requests per model in the ledger.', Object.entries(lifetime.perModel).map(([model, m]) => [{ model, provider: m.provider }, m.requests]));
+        metric('dario_ledger_consumer_api_equivalent_usd', 'Lifetime API-equivalent spend per consumer, USD.', Object.entries(lifetime.perConsumer).map(([consumer, c]) => [{ consumer }, c.apiEquivalentCost]));
+    }
+    return out.join('\n') + '\n';
+}

package/dist/proxy.d.ts

@@ -280,6 +280,7 @@ interface ProxyOptions {
     model?: string;
     fastModel?: string;
     noClaudeAuth?: boolean;
+    analyticsToken?: string;
     /**
      * Override the fetch used for UPSTREAM calls (api.anthropic.com). Test seam:
      * it makes the request path hermetic, which the 400-recovery chain needs —
@@ -628,6 +629,14 @@ export declare function sanitizeError(err: unknown): string;
  * API-key auth via DARIO_API_KEY (x-api-key or Authorization: Bearer).
  * If unset, requests are allowed (loopback-only default). Exported for tests.
  */
+/**
+ * The read-only analytics surfaces — the only paths the analytics token
+ * (`--analytics-token` / `DARIO_ANALYTICS_TOKEN`) is accepted on. Exact
+ * matches on purpose: a prefix test would let a future `/analytics/reset`
+ * inherit read-only auth by accident.
+ */
+export declare const ANALYTICS_READ_PATHS: readonly string[];
+export declare function isAnalyticsReadPath(urlPath: string): boolean;
 export declare function authenticateRequest(headers: IncomingMessage['headers'], apiKeyBuf: Buffer | null): boolean;
 /**
  * Describe WHY authenticateRequest rejected, for operator-facing logs only.

package/dist/proxy.js

@@ -17,6 +17,8 @@ import { backfillIdentity } from './accounts.js';
 import { PoolSync, DEFAULT_POOL_SYNC_INTERVAL_MS } from './pool-sync.js';
 import { Analytics, billingBucketFromClaim, formatUsageLogLine, SUBSCRIPTION_CLAIMS, consumerFromHeader, consumerFromBody, CONSUMER_HEADER, CODEX_CLAIM } from './analytics.js';
 import { Ledger, resolveLedgerPath, ledgerDisabledByEnv } from './ledger.js';
+import { renderPrometheus } from './metrics.js';
+import { renderSpendDonuts, renderAnalyticsView, ANALYTICS_UI_SHELL } from './donuts.js';
 import { KeyStore, keyAllowsModel, resolveKeysPath, looksLikeNamedKey } from './keys.js';
 import { OverageGuard, buildHaltErrorBody } from './overage-guard.js';
 import { notify as osNotify } from './notify.js';
@@ -1006,6 +1008,18 @@ export function sanitizeError(err) {
  * API-key auth via DARIO_API_KEY (x-api-key or Authorization: Bearer).
  * If unset, requests are allowed (loopback-only default). Exported for tests.
  */
+/**
+ * The read-only analytics surfaces — the only paths the analytics token
+ * (`--analytics-token` / `DARIO_ANALYTICS_TOKEN`) is accepted on. Exact
+ * matches on purpose: a prefix test would let a future `/analytics/reset`
+ * inherit read-only auth by accident.
+ */
+export const ANALYTICS_READ_PATHS = [
+    '/analytics', '/analytics/ledger', '/analytics/stream', '/analytics/view', '/analytics/donuts.svg', '/metrics',
+];
+export function isAnalyticsReadPath(urlPath) {
+    return ANALYTICS_READ_PATHS.includes(urlPath);
+}
 export function authenticateRequest(headers, apiKeyBuf) {
     if (!apiKeyBuf)
         return true;
@@ -1970,6 +1984,17 @@ export async function startProxy(opts = {}) {
     // Optional proxy authentication — pre-encode key buffer for performance
     const apiKey = process.env.DARIO_API_KEY;
     const apiKeyBuf = apiKey ? Buffer.from(apiKey) : null;
+    // Read-only analytics credential (dario#1341). Accepted ONLY on the
+    // read-only surfaces listed in isAnalyticsReadPath — never on /v1/*, never
+    // on /admin/*, never on /accounts — so a Grafana box or a browser tab can
+    // hold it without holding request rights. On an unkeyed proxy it changes
+    // nothing (everything is already open on loopback). When DARIO_API_KEY is
+    // set, the root key keeps working on these paths too.
+    const analyticsToken = opts.analyticsToken || process.env.DARIO_ANALYTICS_TOKEN || '';
+    const analyticsTokenBuf = analyticsToken ? Buffer.from(analyticsToken) : null;
+    if (analyticsTokenBuf && !apiKeyBuf) {
+        console.warn('[dario] --analytics-token set but DARIO_API_KEY is not: /analytics and /metrics are already open on this proxy, the token gates nothing.');
+    }
     // Named keys (dario#1318): one credential per developer, hashes on disk,
     // re-read when the file moves. Attribution and per-key limits ride on the
     // match; the root DARIO_API_KEY keeps working beside them.
@@ -2515,7 +2540,19 @@ export async function startProxy(opts = {}) {
             if (handled)
                 return;
         }
-        const requestAuth = resolveRequestAuth(req);
+        // The dashboard shell carries no data, so it needs no credential: it is
+        // the page that ASKS for the token and then fetches /analytics/view.
+        if (urlPath === '/analytics/ui' && req.method === 'GET') {
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', ...SECURITY_HEADERS });
+            res.end(ANALYTICS_UI_SHELL);
+            return;
+        }
+        // Read-only analytics token: accepted on the read-only surfaces only.
+        // Anything else falls through to the normal request auth below.
+        const analyticsRead = isAnalyticsReadPath(urlPath) && req.method === 'GET';
+        const requestAuth = (analyticsRead && analyticsTokenBuf && authenticateRequest(req.headers, analyticsTokenBuf))
+            ? { ok: true, key: null }
+            : resolveRequestAuth(req);
         if (!requestAuth.ok) {
             if (verbose) {
                 // Silent auth rejects are hard to diagnose when a client's config
@@ -2673,6 +2710,40 @@ export async function startProxy(opts = {}) {
             res.end(JSON.stringify({ ...analytics.summary(), queue: queue.snapshot(), lifetime: ledger ? ledger.summary() : null }));
             return;
         }
+        // Prometheus text exposition of the same state (dario#1341). A view, not
+        // new collection: a scrape costs what GET /analytics costs. Same gate.
+        if (urlPath === '/metrics' && req.method === 'GET') {
+            const body = renderPrometheus({
+                summary: analytics.summary(),
+                queue: queue.snapshot(),
+                lifetime: ledger ? ledger.summary() : null,
+                recent: analytics.recent(1000),
+                version: darioVersion(),
+            });
+            res.writeHead(200, { 'Content-Type': 'text/plain; version=0.0.4; charset=utf-8', ...SECURITY_HEADERS });
+            res.end(body);
+            return;
+        }
+        // Spend donuts — by model, by key, by billing — from the ledger. The same
+        // SVG `dario usage --donut` writes to disk.
+        if (urlPath === '/analytics/donuts.svg' && req.method === 'GET') {
+            if (!ledger) {
+                res.writeHead(404, JSON_HEADERS);
+                res.end(JSON.stringify({ error: 'ledger disabled', hint: 'start without --no-ledger / DARIO_LEDGER=0' }));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'image/svg+xml; charset=utf-8', ...SECURITY_HEADERS });
+            res.end(renderSpendDonuts(ledger.summary()));
+            return;
+        }
+        // The server-rendered body behind /analytics/ui. Gated like /analytics;
+        // the shell fetches it with whatever the viewer typed.
+        if (urlPath === '/analytics/view' && req.method === 'GET') {
+            const s = analytics.summary();
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', ...SECURITY_HEADERS });
+            res.end(renderAnalyticsView({ ...s, queue: queue.snapshot() }, ledger ? ledger.summary() : null, darioVersion()));
+            return;
+        }
         // The ledger's per-day table, for anyone charting it. `lifetime` on
         // /analytics is the summary; this is the data behind it.
         if (urlPath === '/analytics/ledger' && req.method === 'GET') {

package/docs/analytics.md

@@ -0,0 +1,60 @@
+# Analytics, `/metrics`, and the dashboard
+
+dario keeps two kinds of numbers. The **rolling window** (`src/analytics.ts`) lives in memory and forgets on restart: per-request records with tokens, latency, seat, model, consumer and billing claim, summarised over the last 60 minutes and since start. The **ledger** (`src/ledger.ts`, `~/.dario/ledger.json`) survives restarts: one row per day, per model, per billing bucket, priced at read time from the published rate cards.
+
+Every surface below is a view over those two. Nothing here collects anything new.
+
+## Surfaces
+
+| path | what | format |
+|---|---|---|
+| `GET /analytics` | window summary + `queue` snapshot + `lifetime` ledger summary | JSON |
+| `GET /analytics/ledger` | the ledger's per-day table | JSON |
+| `GET /analytics/stream` | live tail of request records (drives the TUI) | SSE |
+| `GET /metrics` | the same state as Prometheus text exposition | text/plain 0.0.4 |
+| `GET /analytics/donuts.svg` | spend by model / by key / by billing | SVG |
+| `GET /analytics/view` | server-rendered dashboard body | HTML fragment |
+| `GET /analytics/ui` | the dashboard shell (no data; asks for the token, loads `/view` every 60 s) | HTML page |
+
+CLI: `dario usage` prints the ledger; `--json` dumps `/analytics`; `--card[=file]` writes the share card; `--donut[=file]` writes the three rings.
+
+## Who can read them
+
+By default the proxy binds loopback and these paths need no credential. With `DARIO_API_KEY` set, they need the key like everything else.
+
+`--analytics-token=<secret>` (or `DARIO_ANALYTICS_TOKEN`) adds a **read-only** credential accepted on exactly the paths in the table above, on `GET` only. It is refused on `/v1/*`, `/accounts`, `/status`, `/admin/*`, and any non-GET. That is the point: a Grafana box or a browser tab can hold the numbers without holding request rights. The root key keeps working on the analytics paths too. On an unkeyed proxy the token gates nothing, and the proxy says so at startup.
+
+`/analytics/ui` itself is served without a credential because it contains no data. It stores the token you type in `sessionStorage` and sends it as a bearer on every fetch of `/analytics/view`.
+
+## `/metrics` families
+
+Names ending in `_total` are counters; everything else is a gauge. Labels are escaped per the exposition format.
+
+| family | labels | source |
+|---|---|---|
+| `dario_info` | `version` | always 1 |
+| `dario_requests_total`, `dario_tokens_total{kind}`, `dario_estimated_cost_usd_total`, `dario_error_rate` | `kind` ∈ input, output, cache_read, cache_create, thinking | since start |
+| `dario_window_requests`, `_avg_latency_ms`, `_error_rate`, `_cached_prompt_percent`, `_estimated_cost_usd` | `window_minutes` | rolling window |
+| `dario_window_billing_requests` | `bucket` ∈ subscription, subscription_fallback, extra_usage, api, unknown | claims folded by `billingBucketFromClaim` |
+| `dario_account_requests_total`, `dario_account_estimated_cost_usd`, `dario_account_utilization{window}` | `account`, `window` ∈ 5h, 7d | last rate-limit headers per seat |
+| `dario_model_requests_total`, `dario_model_estimated_cost_usd` | `model` | since start |
+| `dario_consumer_requests_total`, `dario_consumer_estimated_cost_usd` | `consumer` (named key or `x-dario-consumer`) | since start |
+| `dario_queue_active`, `_queued`, `_max_concurrent`, `_max_queued`, `_stalled`, `_max_wait_ms`, `_consumers_active` | — | request queue |
+| `dario_request_latency_ms{quantile}` + `_sum`, `_count` | `quantile` ∈ 0.5, 0.9, 0.99 | nearest-rank over the most recent 1,000 records |
+| `dario_predicted_exhaustion_minutes` (omitted when unknown), `dario_burn_tokens_per_minute`, `dario_burn_cost_usd_per_minute` | — | window predictions |
+| `dario_ledger_requests_total`, `_api_equivalent_usd`, `_metered_usd`, `_recent_api_equivalent_usd{window}`, `_model_api_equivalent_usd{model,provider}`, `_model_requests_total{model,provider}`, `_consumer_api_equivalent_usd{consumer}` | `window` ∈ today, 7d, 30d | ledger (absent when the ledger is off) |
+
+Latency here is end-to-end through dario as the client saw it. Time-to-first-token and the split between dario's own overhead and the provider's time are not recorded per request today; they are the natural next columns on `RequestRecord` if a scrape wants them.
+
+A minimal scrape config:
+
+```yaml
+scrape_configs:
+  - job_name: dario
+    static_configs: [{ targets: ['127.0.0.1:3456'] }]
+    authorization: { credentials: '<DARIO_ANALYTICS_TOKEN>' }
+```
+
+## The rings
+
+`dario usage --donut` and `/analytics/donuts.svg` render the ledger's lifetime spend as three rings: **by model**, **by key** (empty until a named key or `x-dario-consumer` has traffic), and **subscription vs metered**. Each ring keeps the top five and folds the rest into *other*. Shares are of API-equivalent plus metered spend, so a model that only ever ran on an API key still shows.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askalf/dario",
-  "version": "6.8.11",
+  "version": "6.8.12",
   "description": "Use your Claude and ChatGPT subscriptions in Cursor, Cline, Aider, Claude Code and the Agent SDK — at subscription pricing, not per-token API bills. One local Anthropic + OpenAI-compatible endpoint: either plan answers either wire shape, with automatic failover when one hits its limit.",
   "type": "module",
   "bin": {