codex-copilot-dx 0.8.7 → 0.8.9

package/README.md

@@ -213,6 +213,12 @@ If a configured npm mirror has not synchronized the current release yet, use the
 
 ## Diagnostics
 
+### Local dashboard
+
+After starting `ccdx`, open [http://127.0.0.1:2026/](http://127.0.0.1:2026/) in a browser. If `ADAPTER_PORT` is customized, use that port instead. The dashboard shares the existing adapter listener; CCDX does not open a browser automatically or start another service. The page and its assets require both a loopback connection and a loopback Host header, even when LAN binding is enabled.
+
+The dashboard loads local status, a live GitHub Copilot model directory, and a summary of local usage metadata once when opened. Each section has an explicit Refresh control; nothing polls in the background. The appearance button switches between the default dark terminal theme (sun icon) and a light theme (moon icon); the choice is stored only in that browser. The live model table uses the same fresh account validation and selectable GPT filtering as `ccdx models`, never labels cached fallback data as online, and makes no inference request. A catalog listing does not guarantee inference access. The Usage table combines the current and rotated local usage logs, shows totals and up to 100 model rows, and contains no prompt, response body, or credential fields. The animation selector previews the existing themes and saves through the same settings writer as `ccdx animation`; changes take effect on the next adapter start, and `CCDX_TERMINAL_ANIMATION=off` still disables terminal motion. Dashboard data requests require a custom header that cross-site simple requests cannot send; animation writes also require a matching same-origin `Origin`. The dashboard does not initialize the optional image handler. The overview's known-model count is the adapter's current in-memory catalog, not the live table. A missing image-generation status does not prove the feature is disabled: use `ccdx image-status` to check setup. Recent upstream error prose may contain sensitive details, so review the page before sharing screenshots.
+
 Inspect only the local Codex configuration:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Use Codex App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -7,6 +7,7 @@ import {
   classifyAdapterRoute,
   createRequestMetrics,
   isLoopbackAddress,
+  isLoopbackHostHeader,
   runtimeStatusPayload,
 } from "./observability.mjs";
 import { createRequestId, runWithRequestContext } from "./request-context.mjs";
@@ -63,6 +64,8 @@ export {
 } from "./responses-request.mjs";
 
 const ADAPTER_RUNTIME_CONFIG = loadRuntimeConfig();
+const DASHBOARD_PATHS = new Set(["/", "/ui.css", "/theme.js", "/ui.js"]);
+const DASHBOARD_API_PATHS = new Set(["/_ccdx/ui/animation", "/_ccdx/ui/models/live", "/_ccdx/ui/usage"]);
 
 export function requestPath(reqUrl) {
   return new URL(reqUrl || "/", "http://localhost").pathname;
@@ -200,6 +203,14 @@ export function createAdapterHandler(options = {}) {
     upstreamTimeoutMs,
   });
   const dispatch = async (req, res, pathname) => {
+    if (DASHBOARD_API_PATHS.has(pathname)) {
+      const { handleDashboardApi } = await import("./dashboard-api.mjs");
+      return handleDashboardApi(req, res, pathname, options.dashboardOptions);
+    }
+    if ((req.method === "GET" || req.method === "HEAD") && DASHBOARD_PATHS.has(pathname)) {
+      const { serveDashboard } = await import("./dashboard.mjs");
+      return serveDashboard(req, res, pathname);
+    }
     if (pathname === "/mcp/image") {
       if (imageMcpHandler) return imageMcpHandler(req, res);
       return import("./image-mcp.mjs").then(({ createImageMcpHandler }) => {
@@ -208,7 +219,7 @@ export function createAdapterHandler(options = {}) {
       });
     }
     if (req.method === "GET" && pathname === ADAPTER_STATUS_PATH) {
-      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+      if (!isLoopbackAddress(req.socket?.remoteAddress) || !isLoopbackHostHeader(req.headers?.host)) {
         res.writeHead(403, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Runtime status is available only from loopback" }));
         return;
@@ -235,7 +246,7 @@ export function createAdapterHandler(options = {}) {
     }
 
     if (pathname === ADAPTER_CACHE_PATH) {
-      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+      if (!isLoopbackAddress(req.socket?.remoteAddress) || !isLoopbackHostHeader(req.headers?.host)) {
         res.writeHead(403, { "Content-Type": "application/json" });
         res.end(JSON.stringify({ error: "Cache control is available only from loopback" }));
         return;
@@ -373,7 +384,9 @@ export function createAdapterHandler(options = {}) {
 
     const trackRequest = pathname !== ADAPTER_HEALTH_PATH
       && pathname !== ADAPTER_STATUS_PATH
-      && pathname !== ADAPTER_CACHE_PATH;
+      && pathname !== ADAPTER_CACHE_PATH
+      && !DASHBOARD_API_PATHS.has(pathname)
+      && !((req.method === "GET" || req.method === "HEAD") && DASHBOARD_PATHS.has(pathname));
     const routeName = classifyAdapterRoute(req.method, pathname);
     const complete = trackRequest ? requestMetrics.begin(routeName) : () => {};
     const streamPerformance = trackRequest ? streamPerformanceMetrics.begin(routeName) : null;

package/src/dashboard/index.html

@@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta name="color-scheme" content="dark light">
+    <link rel="icon" href="data:,">
+    <script src="/theme.js"></script>
+    <link rel="stylesheet" href="/ui.css">
+    <script src="/ui.js" defer></script>
+    <title>CCDX · Local dashboard</title>
+  </head>
+  <body>
+    <div class="shell">
+      <header class="topbar">
+        <div class="brand">CCDX <span class="brand-detail">/ LOCAL STATUS</span></div>
+        <div class="topbar-actions"><span id="connection" class="badge neutral" role="status">READING</span><button id="theme-toggle" class="icon-button" type="button" aria-label="Switch to light mode" title="Switch to light mode"><svg class="icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2M4.93 4.93l1.42 1.42m11.3 11.3 1.42 1.42M2 12h2m16 0h2M4.93 19.07l1.42-1.42m11.3-11.3 1.42-1.42"/></svg><svg class="icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M20.4 15.6A8.5 8.5 0 0 1 8.4 3.6 8.5 8.5 0 1 0 20.4 15.6Z"/></svg></button><button id="refresh" type="button">Refresh</button></div>
+      </header>
+
+      <main>
+        <section class="intro">
+          <h1><span aria-hidden="true">$</span> ccdx status</h1>
+          <p id="updated">Reading status…</p>
+        </section>
+
+        <section class="overview" aria-label="Overview">
+          <article class="card"><h2>ADAPTER</h2><strong id="version">—</strong><p id="uptime">—</p></article>
+          <article class="card"><h2>COPILOT</h2><strong id="copilot">—</strong><p id="token">—</p></article>
+          <article class="card"><h2>KNOWN MODELS</h2><strong id="models">—</strong><p id="model-source">—</p></article>
+          <article class="card"><h2>REQUESTS</h2><strong id="requests">—</strong><p id="request-errors">—</p></article>
+        </section>
+
+        <section class="details" aria-label="Runtime details">
+          <article class="panel">
+            <div class="panel-heading"><h2>MODEL OUTCOMES</h2><span>RESPONSES</span></div>
+            <dl class="stats"><div><dt>Completed</dt><dd id="completed">—</dd></div><div><dt>Incomplete</dt><dd id="incomplete">—</dd></div><div><dt>Failed</dt><dd id="failed">—</dd></div><div><dt>Cancelled</dt><dd id="cancelled">—</dd></div></dl>
+            <p class="hint">HTTP 2xx != model completed.</p>
+          </article>
+          <article class="panel">
+            <div class="panel-heading"><h2>LOCAL HISTORY</h2><span>MEMORY</span></div>
+            <strong id="history">—</strong><progress id="history-meter" class="meter" max="100" value="0" aria-label="History cache usage"></progress>
+            <p id="history-detail" class="hint">—</p>
+          </article>
+          <article class="panel">
+            <div class="panel-heading"><h2>IMAGE GENERATION</h2><span>OPTIONAL</span></div>
+            <strong id="image">—</strong><p id="image-detail" class="hint">—</p>
+          </article>
+        </section>
+
+        <section class="panel dashboard-section" aria-label="Terminal animation">
+          <div class="panel-heading"><h2>TERMINAL ANIMATION</h2><span id="animation-state">READING</span></div>
+          <div id="animation-options" class="animation-options" role="group" aria-label="Animation theme"></div>
+          <div class="section-actions"><button id="save-animation" type="button" disabled>Save selection</button><span id="animation-note" role="status">Applies on next ccdx start.</span></div>
+        </section>
+
+        <section class="panel dashboard-section" aria-label="Live upstream models">
+          <div class="panel-heading"><h2>UPSTREAM GPT MODELS</h2><div class="heading-actions"><span id="models-state">CHECKING LIVE</span><button id="refresh-models" type="button">Refresh</button></div></div>
+          <p id="models-note" class="table-note">Querying GitHub Copilot…</p>
+          <div class="table-wrap"><table><thead><tr><th scope="col">MODEL</th><th scope="col">VENDOR</th><th scope="col">API</th><th scope="col">FLAG</th></tr></thead><tbody id="live-models-body"><tr><td colspan="4">Loading…</td></tr></tbody></table></div>
+          <p class="hint">Catalog listing does not guarantee inference access.</p>
+        </section>
+
+        <section class="panel dashboard-section" aria-label="Usage by model">
+          <div class="panel-heading"><h2>USAGE</h2><div class="heading-actions"><span id="usage-state">READING LOG</span><button id="refresh-usage" type="button">Refresh</button></div></div>
+          <p id="usage-note" class="table-note">Aggregating local usage metadata…</p>
+          <div class="table-wrap"><table class="usage-table"><thead><tr><th scope="col">MODEL</th><th scope="col">CALLS</th><th scope="col">INPUT</th><th scope="col">CACHE READ</th><th scope="col">OUTPUT</th><th scope="col">TOTAL</th></tr></thead><tbody id="usage-body"><tr><td colspan="6">Loading…</td></tr></tbody></table></div>
+        </section>
+
+        <section class="lower" aria-label="Recent failures">
+          <div class="panel-heading"><h2>RECENT UPSTREAM FAILURES</h2><span>response.failed</span></div>
+          <ol id="failures"><li class="empty">Reading…</li></ol>
+          <p class="hint">Upstream messages may contain sensitive text.</p>
+        </section>
+      </main>
+
+      <footer>LOCAL ONLY / NO BACKGROUND POLLING</footer>
+    </div>
+  </body>
+</html>

package/src/dashboard/theme.js

@@ -0,0 +1,24 @@
+(() => {
+  const key = "ccdx.dashboard.theme";
+  let theme = "dark";
+  try {
+    if (localStorage.getItem(key) === "light") theme = "light";
+  } catch { /* Private browsing may disable storage. */ }
+  document.documentElement.dataset.theme = theme;
+
+  document.addEventListener("DOMContentLoaded", () => {
+    const button = document.getElementById("theme-toggle");
+    const updateLabel = () => {
+      const label = `Switch to ${theme === "dark" ? "light" : "dark"} mode`;
+      button.setAttribute("aria-label", label);
+      button.title = label;
+    };
+    updateLabel();
+    button.addEventListener("click", () => {
+      theme = theme === "dark" ? "light" : "dark";
+      document.documentElement.dataset.theme = theme;
+      try { localStorage.setItem(key, theme); } catch { /* Keep the current selection. */ }
+      updateLabel();
+    });
+  });
+})();

package/src/dashboard/ui.css

@@ -0,0 +1,88 @@
+:root { color-scheme: dark; font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace; --page: #0b110d; --surface: #111a13; --text: #e0e9df; --strong: #f0f6ec; --muted: #9aada0; --badge: #a9b9aa; --subtle: #78917d; --quiet: #6d8371; --footer: #617966; --border: #2b3b2f; --top-border: #2a3a2e; --accent: #a6f5a8; --accent-soft: #84e99e; --heading: #83b98b; --bad: #ff947e; --failed: #ff9f91; --incomplete: #e3c77c; --button-border: #45634b; --button-bg: #152219; --button-fg: #b2f1bd; --button-hover: #203526; --selected-bg: #192a1d; --option-hover: #1a2a1e; --table-text: #d8e2d8; --preview: #657d69; --ansi-white: #f5fff5; --ansi-159: #9af5e9; --ansi-123: #75e4d9; --ansi-87: #5ad0d4; --ansi-51: #42b9d8; --ansi-45: #3ca2d0; --ansi-39: #4389c2; --ansi-33: #4775b2; }
+:root[data-theme="light"] { color-scheme: light; --page: #f5f8f3; --surface: #ffffff; --text: #1b2b20; --strong: #122219; --muted: #475d4e; --badge: #475d4e; --subtle: #4b6652; --quiet: #55715c; --footer: #59735f; --border: #c4d2c5; --top-border: #b8c9ba; --accent: #176b3a; --accent-soft: #176b3a; --heading: #235f37; --bad: #a33625; --failed: #a33625; --incomplete: #835600; --button-border: #79a085; --button-bg: #ebf4ec; --button-fg: #185b32; --button-hover: #dbeedd; --selected-bg: #e4f3e7; --option-hover: #edf6ee; --table-text: #233b2b; --preview: #596f60; --ansi-white: #234231; --ansi-159: #116b64; --ansi-123: #0d7771; --ansi-87: #116b75; --ansi-51: #14697e; --ansi-45: #1a6183; --ansi-39: #265f8d; --ansi-33: #365a8d; }
+* { box-sizing: border-box; }
+body { margin: 0; color: var(--text); background: var(--page); font-size: 13px; }
+.shell { max-width: 1220px; margin: 0 auto; padding: 0 24px; }
+.topbar { min-height: 68px; display: flex; justify-content: space-between; align-items: center; gap: 20px; border-bottom: 1px solid var(--top-border); }
+.brand { color: var(--accent); font-size: 16px; font-weight: 750; letter-spacing: .07em; white-space: nowrap; }
+.brand-detail { color: var(--subtle); font-size: 11px; font-weight: 500; letter-spacing: .03em; }
+.topbar-actions { display: flex; align-items: center; gap: 20px; }
+.badge { color: var(--badge); white-space: nowrap; font-size: 11px; font-weight: 650; text-transform: uppercase; }
+.badge::before { content: "●"; margin-right: 8px; }
+.badge.good { color: var(--accent-soft); }
+.badge.bad { color: var(--bad); }
+button { border: 1px solid var(--button-border); border-radius: 2px; background: var(--button-bg); color: var(--button-fg); padding: 8px 13px; font: inherit; font-size: 11px; font-weight: 700; text-transform: uppercase; cursor: pointer; }
+button:hover { background: var(--button-hover); }
+button:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+button:disabled { opacity: .55; cursor: wait; }
+.icon-button { display: inline-flex; align-items: center; justify-content: center; width: 34px; height: 34px; padding: 6px; }
+.icon-button svg { width: 18px; height: 18px; }
+.icon-moon, :root[data-theme="light"] .icon-sun { display: none; }
+:root[data-theme="light"] .icon-moon { display: block; }
+.intro { display: flex; justify-content: space-between; align-items: baseline; gap: 20px; padding: 38px 0 25px; }
+h1 { margin: 0; font-size: clamp(20px, 3vw, 27px); font-weight: 650; letter-spacing: -.035em; }
+h1 span { color: var(--accent-soft); }
+.intro p { margin: 0; color: var(--subtle); font-size: 11px; }
+.overview { display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 11px; }
+.card, .panel, .lower { min-width: 0; background: var(--surface); border: 1px solid var(--border); border-radius: 2px; }
+.card { min-height: 139px; padding: 18px; }
+.card h2, .panel h2, .lower h2 { color: var(--heading); font-size: 11px; font-weight: 700; letter-spacing: .08em; margin: 0; }
+.card strong, .panel > strong { display: block; margin-top: 21px; color: var(--strong); font-size: 23px; font-weight: 650; line-height: 1.25; letter-spacing: -.035em; overflow-wrap: anywhere; }
+.card p { margin: 9px 0 0; color: var(--muted); font-size: 11px; line-height: 1.45; overflow-wrap: anywhere; }
+.details { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 11px; margin-top: 11px; }
+.panel { min-height: 205px; padding: 18px; }
+.panel-heading { display: flex; justify-content: space-between; align-items: baseline; gap: 10px; }
+.panel-heading span { color: var(--quiet); font-size: 10px; white-space: nowrap; }
+.stats { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 17px; margin: 26px 0 0; }
+.stats div { display: flex; justify-content: space-between; border-bottom: 1px solid var(--border); padding-bottom: 8px; gap: 8px; }
+.stats dt { color: var(--muted); font-size: 11px; }
+.stats dd { margin: 0; font-size: 14px; font-weight: 650; }
+#incomplete { color: var(--incomplete); }
+#failed { color: var(--failed); }
+.hint { color: var(--subtle); font-size: 11px; line-height: 1.5; margin: 15px 0 0; overflow-wrap: anywhere; }
+.meter { display: block; width: 100%; height: 6px; border: 0; border-radius: 0; background: var(--border); margin-top: 20px; appearance: none; }
+.meter::-webkit-progress-bar { background: var(--border); }
+.meter::-webkit-progress-value { background: var(--accent-soft); }
+.meter::-moz-progress-bar { background: var(--accent-soft); }
+.dashboard-section { min-height: 0; margin-top: 11px; }
+.heading-actions { display: flex; align-items: center; gap: 16px; }
+.heading-actions button { padding: 5px 9px; }
+.animation-options { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px; margin-top: 18px; }
+.theme-option { display: grid; grid-template-columns: 18px 76px minmax(0, 1fr); align-items: center; gap: 8px; min-width: 0; width: 100%; border: 1px solid var(--border); padding: 10px; background: transparent; color: var(--text); text-align: left; text-transform: none; font-size: 11px; cursor: pointer; }
+.theme-option::before { content: "○"; color: var(--subtle); font-size: 17px; line-height: 1; }
+.theme-option[aria-pressed="true"] { border-color: var(--accent-soft); background: var(--selected-bg); }
+.theme-option[aria-pressed="true"]::before { content: "●"; color: var(--accent-soft); }
+.theme-option:hover { background: var(--option-hover); }
+.theme-name { color: var(--text); font-size: 11px; white-space: nowrap; }
+.theme-name small { display: block; color: var(--subtle); font-size: 9px; margin-top: 2px; }
+.theme-preview { color: var(--preview); white-space: pre; overflow: hidden; font-size: 11px; letter-spacing: 0; }
+.ansi-white { color: var(--ansi-white); }
+.ansi-159 { color: var(--ansi-159); }
+.ansi-123 { color: var(--ansi-123); }
+.ansi-87 { color: var(--ansi-87); }
+.ansi-51 { color: var(--ansi-51); }
+.ansi-45 { color: var(--ansi-45); }
+.ansi-39 { color: var(--ansi-39); }
+.ansi-33 { color: var(--ansi-33); }
+.section-actions { display: flex; align-items: center; gap: 15px; margin-top: 16px; }
+.section-actions span { color: var(--muted); font-size: 11px; }
+.table-note { margin: 15px 0 8px; color: var(--muted); font-size: 11px; }
+.table-wrap { width: 100%; overflow-x: auto; }
+table { width: 100%; border-collapse: collapse; font-size: 11px; }
+th { color: var(--heading); text-align: left; font-weight: 700; letter-spacing: .05em; }
+th, td { padding: 9px 12px 9px 0; border-bottom: 1px solid var(--border); white-space: nowrap; }
+th:last-child, td:last-child { padding-right: 0; }
+td { color: var(--table-text); }
+.usage-table th:not(:first-child), .usage-table td:not(:first-child) { text-align: right; }
+.usage-table tr.total-row td { color: var(--accent); font-weight: 700; }
+.lower { margin-top: 11px; padding: 18px; }
+.lower ol { list-style: none; margin: 16px 0 0; padding: 0; }
+.lower li { display: grid; grid-template-columns: minmax(150px, 1fr) minmax(0, 2fr); gap: 14px; padding: 9px 0; border-top: 1px solid var(--border); font-size: 11px; }
+.lower li strong, .lower li span { overflow-wrap: anywhere; }
+.lower li strong { color: var(--text); font-weight: 650; }
+.lower li span, .lower li.empty { color: var(--muted); line-height: 1.5; }
+footer { color: var(--footer); font-size: 10px; letter-spacing: .05em; padding: 22px 0 30px; }
+@media (max-width: 1000px) { .animation-options { grid-template-columns: repeat(2, minmax(0, 1fr)); } }
+@media (max-width: 900px) { .overview { grid-template-columns: repeat(2, minmax(0, 1fr)); } .details { grid-template-columns: repeat(2, minmax(0, 1fr)); } .details .panel:last-child { grid-column: 1 / -1; } }
+@media (max-width: 680px) { .animation-options { grid-template-columns: 1fr; } }
+@media (max-width: 620px) { .shell { padding: 0 16px; } .topbar { min-height: 60px; } .brand-detail { display: none; } .topbar-actions { gap: 11px; } .intro { display: block; padding: 29px 0 21px; } .intro p { margin-top: 9px; } .overview, .details { grid-template-columns: 1fr; } .details .panel:last-child { grid-column: auto; } .card { min-height: 122px; } .card strong { margin-top: 14px; } .lower li { display: block; } .lower li span { display: block; margin-top: 5px; } }

package/src/dashboard/ui.js

@@ -0,0 +1,347 @@
+const element = (id) => document.getElementById(id);
+const text = (id, value) => { element(id).textContent = value; };
+const finite = (value) => value !== null && value !== undefined && Number.isFinite(Number(value));
+const number = (value) => finite(value) ? Math.max(0, Math.round(Number(value))).toLocaleString() : "—";
+const mib = (value) => finite(value) ? `${(Number(value) / 1048576).toFixed(1)} MiB` : "—";
+
+function duration(value) {
+  if (!finite(value)) return "—";
+  const seconds = Math.max(0, Math.round(Number(value) / 1000));
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  return days ? `${days}d ${hours}h` : hours ? `${hours}h ${minutes}m` : `${minutes}m`;
+}
+
+function renderFailures(recent) {
+  const list = element("failures");
+  list.replaceChildren();
+  const failures = Array.isArray(recent) ? recent.slice(-5).reverse() : [];
+  if (!failures.length) {
+    const item = document.createElement("li");
+    item.className = "empty";
+    item.textContent = "No response.failed events recorded.";
+    list.append(item);
+    return;
+  }
+  for (const failure of failures) {
+    const item = document.createElement("li");
+    const title = document.createElement("strong");
+    const detail = document.createElement("span");
+    title.textContent = `${String(failure.model || "unknown_model").slice(0, 80)} / ${String(failure.code || "unknown_error").slice(0, 80)}`;
+    detail.textContent = `${String(failure.message || "No message").slice(0, 240)}${failure.retried ? " / retried" : ""}`;
+    item.append(title, detail);
+    list.append(item);
+  }
+}
+
+function render(data) {
+  text("version", `v${data.version || "?"}`);
+  text("uptime", `pid ${number(data.pid)} / uptime ${duration(data.uptime_ms)}`);
+
+  const copilot = data.copilot || {};
+  text("copilot", copilot.account_bound ? "BOUND" : "UNCONFIRMED");
+  text("token", copilot.token_cached ? `service token / TTL ${duration(copilot.token_expires_in_ms)}` : "service token not cached");
+
+  const models = data.models || {};
+  text("models", number(models.models));
+  text("model-source", `source ${String(models.source || "unknown").slice(0, 80)} / live: ccdx models`);
+
+  const requests = data.requests || {};
+  text("requests", number(requests.total));
+  text("request-errors", `4xx ${number(requests.status_4xx)} / 5xx ${number(requests.status_5xx)} / active ${number(requests.active)}`);
+
+  const outcomes = data.stream_performance?.by_route?.responses?.terminal_outcomes?.totals || {};
+  for (const key of ["completed", "incomplete", "failed", "cancelled"]) text(key, number(outcomes[key]));
+
+  const history = data.response_history || {};
+  const limit = Number(history.maxBytes || data.limits?.response_history_max_bytes || 0);
+  const used = Number(history.bytes || 0);
+  text("history", `${mib(used)} / ${mib(limit)}`);
+  text("history-detail", `entries ${number(history.entries)} / trees ${number(history.tree_count)} / misses ${number(history.lookup_misses)} (evicted ${number(history.evicted_lookup_misses)})`);
+  element("history-meter").value = limit > 0 ? Math.min(100, Math.max(0, used / limit * 100)) : 0;
+
+  const image = data.image_generation;
+  text("image", image ? `${number(image.succeeded)} succeeded` : "NOT INITIALIZED");
+  text("image-detail", image
+    ? `active ${number(image.active)} / failed ${number(image.failed)} / delivery failures ${number(image.delivery_failures)}`
+    : "Setup state unknown / ccdx image-status");
+
+  renderFailures(data.response_failures?.recent);
+  text("updated", `Snapshot ${new Date().toLocaleTimeString()}`);
+}
+
+async function refresh() {
+  const button = element("refresh");
+  button.disabled = true;
+  text("connection", "READING");
+  element("connection").className = "badge neutral";
+  try {
+    const response = await fetch("/_ccdx/status", {
+      cache: "no-store",
+      headers: { Accept: "application/json" },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const data = await response.json();
+    if (data?.ok !== true || data?.name !== "codex-copilot-dx") throw new Error("Unexpected status response");
+    render(data);
+    text("connection", "LOCAL OK");
+    element("connection").className = "badge good";
+  } catch {
+    text("connection", "UNAVAILABLE");
+    element("connection").className = "badge bad";
+    text("updated", "Status unavailable / check ccdx, then refresh");
+  } finally {
+    button.disabled = false;
+  }
+}
+
+element("refresh").addEventListener("click", refresh);
+refresh();
+
+const animationRows = new Map();
+let animationTimelines = [];
+let savedAnimation = "";
+let selectedAnimation = "";
+let previewDisabledByEnvironment = false;
+let previewVisible = false;
+let previewTimer = null;
+let previewStarted = 0;
+const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+
+function renderAnsiFrame(target, frame) {
+  const fragments = String(frame).split(/\u001b\[([0-9;]+)m/);
+  const content = document.createDocumentFragment();
+  let color = "";
+  for (let index = 0; index < fragments.length; index += 2) {
+    if (fragments[index]) {
+      const span = document.createElement("span");
+      span.className = color;
+      span.textContent = fragments[index];
+      content.append(span);
+    }
+    const code = fragments[index + 1];
+    color = code === "97" ? "ansi-white"
+      : /^38;5;(159|123|87|51|45|39|33)$/.test(code || "") ? `ansi-${code.slice(5)}` : "";
+  }
+  target.replaceChildren(content);
+}
+
+function renderAnimationFrames(elapsed) {
+  for (const timeline of animationTimelines) {
+    const position = timeline.id === selectedAnimation ? elapsed % timeline.duration : 0;
+    const frameIndex = timeline.frames.findIndex(({ until }) => position < until);
+    if (frameIndex === timeline.lastFrame) continue;
+    timeline.lastFrame = frameIndex;
+    renderAnsiFrame(timeline.target, frameIndex < 0 ? `[${" ".repeat(20)}]` : timeline.frames[frameIndex].ansi);
+  }
+}
+
+function stopAnimationPreview() {
+  if (previewTimer !== null) clearTimeout(previewTimer);
+  previewTimer = null;
+}
+
+function tickAnimationPreview() {
+  previewTimer = null;
+  if (!previewVisible || document.visibilityState !== "visible" || reducedMotion.matches || previewDisabledByEnvironment) return;
+  renderAnimationFrames(performance.now() - previewStarted);
+  previewTimer = setTimeout(tickAnimationPreview, 32);
+}
+
+function syncAnimationPreview() {
+  stopAnimationPreview();
+  if (!previewVisible || document.visibilityState !== "visible" || reducedMotion.matches || previewDisabledByEnvironment) {
+    for (const timeline of animationTimelines) timeline.lastFrame = -2;
+    renderAnimationFrames(0);
+    return;
+  }
+  previewStarted = performance.now();
+  tickAnimationPreview();
+}
+
+new IntersectionObserver(([entry]) => {
+  previewVisible = entry.isIntersecting;
+  syncAnimationPreview();
+}).observe(element("animation-options"));
+document.addEventListener("visibilitychange", syncAnimationPreview);
+reducedMotion.addEventListener("change", syncAnimationPreview);
+
+function buildAnimationOptions(data) {
+  const container = element("animation-options");
+  container.replaceChildren();
+  animationRows.clear();
+  animationTimelines = [];
+  savedAnimation = data.theme;
+  selectedAnimation = data.theme;
+  previewDisabledByEnvironment = data.disabled_by_environment === true;
+  for (const [index, theme] of data.themes.entries()) {
+    const option = document.createElement("button");
+    option.type = "button";
+    option.className = "theme-option";
+    option.setAttribute("aria-pressed", String(theme.id === data.theme));
+    option.addEventListener("click", () => {
+      selectedAnimation = theme.id;
+      for (const [id, row] of animationRows) row.setAttribute("aria-pressed", String(id === theme.id));
+      element("save-animation").disabled = selectedAnimation === savedAnimation;
+      syncAnimationPreview();
+    });
+    const name = document.createElement("span");
+    name.className = "theme-name";
+    name.textContent = `${String(index + 1).padStart(2, "0")} ${theme.label}`;
+    if (theme.default) {
+      const marker = document.createElement("small");
+      marker.textContent = "DEFAULT";
+      name.append(marker);
+    }
+    const preview = document.createElement("span");
+    preview.className = "theme-preview";
+    preview.setAttribute("aria-hidden", "true");
+    option.append(name, preview);
+    container.append(option);
+    animationRows.set(theme.id, option);
+    let until = 0;
+    const frames = theme.frames.map((frame) => {
+      until += frame.delay_ms;
+      return { ansi: frame.ansi, until };
+    });
+    animationTimelines.push({ id: theme.id, target: preview, frames, duration: until + theme.loop_pause_ms, lastFrame: -2 });
+  }
+  element("save-animation").disabled = true;
+  syncAnimationPreview();
+}
+
+function animationNote(data) {
+  return data.disabled_by_environment
+    ? "Disabled by CCDX_TERMINAL_ANIMATION; saved choice applies after override removal and next start."
+    : "Saved choice applies on next ccdx start.";
+}
+
+async function loadAnimation() {
+  text("animation-state", "READING");
+  try {
+    const response = await fetch("/_ccdx/ui/animation", { cache: "no-store", headers: { "X-CCDX-Dashboard": "1" }, signal: AbortSignal.timeout(8000) });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || `HTTP ${response.status}`);
+    buildAnimationOptions(data);
+    text("animation-state", `CURRENT ${data.theme.toUpperCase()}`);
+    text("animation-note", animationNote(data));
+  } catch (error) {
+    text("animation-state", "UNAVAILABLE");
+    text("animation-note", String(error.message || error).slice(0, 180));
+  }
+}
+
+async function saveAnimation() {
+  const button = element("save-animation");
+  if (!selectedAnimation || selectedAnimation === savedAnimation) return;
+  button.disabled = true;
+  text("animation-note", "Saving…");
+  try {
+    const response = await fetch("/_ccdx/ui/animation", {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-CCDX-Dashboard": "1" },
+      body: JSON.stringify({ theme: selectedAnimation }),
+      signal: AbortSignal.timeout(8000),
+    });
+    const data = await response.json();
+    if (!response.ok) throw new Error(data.error || `HTTP ${response.status}`);
+    savedAnimation = data.theme;
+    text("animation-state", `CURRENT ${data.theme.toUpperCase()}`);
+    text("animation-note", animationNote(data));
+  } catch (error) {
+    text("animation-note", `Not saved / ${String(error.message || error).slice(0, 150)}`);
+  } finally {
+    button.disabled = selectedAnimation === savedAnimation;
+  }
+}
+
+function emptyTable(bodyId, columns, message) {
+  const body = element(bodyId);
+  body.replaceChildren();
+  const row = document.createElement("tr");
+  const cell = document.createElement("td");
+  cell.colSpan = columns;
+  cell.textContent = message;
+  row.append(cell);
+  body.append(row);
+}
+
+function tableRow(values, { total = false } = {}) {
+  const row = document.createElement("tr");
+  if (total) row.className = "total-row";
+  for (const value of values) {
+    const cell = document.createElement("td");
+    cell.textContent = value;
+    row.append(cell);
+  }
+  return row;
+}
+
+async function loadModels() {
+  const button = element("refresh-models");
+  button.disabled = true;
+  text("models-state", "CHECKING LIVE");
+  text("models-note", "Querying GitHub Copilot…");
+  emptyTable("live-models-body", 4, "Loading…");
+  try {
+    const response = await fetch("/_ccdx/ui/models/live", { cache: "no-store", headers: { "X-CCDX-Dashboard": "1" }, signal: AbortSignal.timeout(15000) });
+    const data = await response.json();
+    if (!response.ok || data.source !== "live") throw new Error(data.error || `HTTP ${response.status}`);
+    const body = element("live-models-body");
+    body.replaceChildren();
+    for (const model of data.models) {
+      body.append(tableRow([model.id, model.vendor, model.endpoints.join(" / "), model.preview ? "preview" : "—"]));
+    }
+    if (!data.models.length) emptyTable("live-models-body", 4, "No selectable GPT models advertised.");
+    text("models-state", "LIVE SNAPSHOT");
+    text("models-note", `${number(data.selectable)} selectable / ${number(data.advertised)} advertised / ${data.upstream_host} / ${new Date(data.checked_at).toLocaleTimeString()}`);
+  } catch (error) {
+    text("models-state", "LIVE LOOKUP FAILED");
+    text("models-note", String(error.message || error).slice(0, 240));
+    emptyTable("live-models-body", 4, "No live catalog available.");
+  } finally {
+    button.disabled = false;
+  }
+}
+
+function usageValues(row) {
+  return [row.model, number(row.requests), number(row.input_tokens), number(row.cache_read_tokens), number(row.output_tokens), number(row.total_tokens)];
+}
+
+async function loadUsage() {
+  const button = element("refresh-usage");
+  button.disabled = true;
+  text("usage-state", "READING LOG");
+  text("usage-note", "Aggregating local usage metadata…");
+  emptyTable("usage-body", 6, "Loading…");
+  try {
+    const response = await fetch("/_ccdx/ui/usage", { cache: "no-store", headers: { "X-CCDX-Dashboard": "1" }, signal: AbortSignal.timeout(15000) });
+    const data = await response.json();
+    if (!response.ok || data.source !== "local_usage_log") throw new Error(data.error || `HTTP ${response.status}`);
+    const body = element("usage-body");
+    body.replaceChildren();
+    if (data.total.requests > 0) {
+      body.append(tableRow(usageValues(data.total), { total: true }));
+      for (const row of data.rows) body.append(tableRow(usageValues(row)));
+    } else {
+      emptyTable("usage-body", 6, "No usage records.");
+    }
+    text("usage-state", "LOCAL LOG");
+    text("usage-note", `${number(data.total.requests)} records / ${number(data.rows.length)} of ${number(data.model_count)} models shown`);
+  } catch (error) {
+    text("usage-state", "LOG UNAVAILABLE");
+    text("usage-note", String(error.message || error).slice(0, 180));
+    emptyTable("usage-body", 6, "No usage summary available.");
+  } finally {
+    button.disabled = false;
+  }
+}
+
+element("save-animation").addEventListener("click", saveAnimation);
+element("refresh-models").addEventListener("click", loadModels);
+element("refresh-usage").addEventListener("click", loadUsage);
+loadAnimation();
+loadModels();
+loadUsage();

package/src/dashboard-api.mjs

@@ -0,0 +1,204 @@
+import os from "node:os";
+import { fetchLiveCopilotModels } from "./cli-models.mjs";
+import { createRequestAbort, readJsonBody } from "./http-transport.mjs";
+import { isLoopbackAddress, isLoopbackHostHeader } from "./observability.mjs";
+import {
+  DEFAULT_TERMINAL_ANIMATION_THEME,
+  getTerminalAnimationFrameDelay,
+  isTerminalAnimationTheme,
+  renderTerminalAnimationFrame,
+  TERMINAL_ANIMATION_THEMES,
+} from "./terminal-animation.mjs";
+import { summarizeUsageLogs } from "./usage.mjs";
+import { readUserSettings, terminalAnimationPreference, writeTerminalAnimationTheme } from "./user-settings.mjs";
+
+const ANIMATION_PATH = "/_ccdx/ui/animation";
+const MODELS_PATH = "/_ccdx/ui/models/live";
+const USAGE_PATH = "/_ccdx/ui/usage";
+const DISABLED_ANIMATION = /^(0|false|no|off)$/i;
+
+function sendJson(res, statusCode, value) {
+  res.writeHead(statusCode, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+  });
+  res.end(JSON.stringify(value));
+}
+
+function safeText(value, length = 160) {
+  return String(value ?? "").replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().slice(0, length);
+}
+
+function liveModelError(error) {
+  const message = String(error?.message || error || "");
+  const status = /\bHTTP (\d{3})\b/.exec(message)?.[1];
+  if (status) return `Live model lookup failed (HTTP ${status}). Run ccdx models for details.`;
+  if (/timed out/i.test(message)) return "Live model lookup timed out. Retry or run ccdx models.";
+  if (/GitHub token not found/i.test(message)) return "GitHub token not found. Start ccdx to sign in.";
+  return "Live model lookup failed. Run ccdx models for details.";
+}
+
+function animationState(env, home, { includeFrames = false } = {}) {
+  readUserSettings({ env, home, strict: true });
+  const preference = terminalAnimationPreference({ env, home });
+  return {
+    theme: preference.theme,
+    source: preference.source,
+    disabled_by_environment: DISABLED_ANIMATION.test(String(env.CCDX_TERMINAL_ANIMATION || "").trim()),
+    themes: TERMINAL_ANIMATION_THEMES.map((theme) => ({
+      id: theme.id,
+      label: theme.label,
+      default: theme.id === DEFAULT_TERMINAL_ANIMATION_THEME,
+      ...(includeFrames ? {
+        loop_pause_ms: theme.loopPauseMs,
+        frames: Array.from({ length: theme.frameCount }, (_, offset) => {
+          const index = theme.startFrame + offset;
+          return {
+            ansi: renderTerminalAnimationFrame(theme.id, index),
+            delay_ms: getTerminalAnimationFrameDelay(theme.id, index),
+          };
+        }),
+      } : {}),
+    })),
+  };
+}
+
+function sameOrigin(req) {
+  const origin = req.headers?.origin;
+  const host = req.headers?.host;
+  if (typeof origin !== "string" || typeof host !== "string") return false;
+  try {
+    return new URL(origin).origin === new URL(`http://${host}`).origin;
+  } catch {
+    return false;
+  }
+}
+
+function finite(value) {
+  return Number.isFinite(value) ? Math.max(0, value) : null;
+}
+
+function cacheReadTokens(usage = {}) {
+  const values = [usage.cache_read_input_tokens, usage.cached_input_tokens].filter(Number.isFinite);
+  return values.length ? values.reduce((sum, value) => sum + value, 0) : null;
+}
+
+function usageRow(model, values) {
+  return {
+    model: safeText(model, 100),
+    requests: finite(values.requests),
+    input_tokens: finite(values.input_tokens),
+    cache_read_tokens: cacheReadTokens(values),
+    output_tokens: finite(values.output_tokens),
+    total_tokens: finite(values.total_tokens),
+  };
+}
+
+function usageTable(summary) {
+  const models = Object.entries(summary.byModel || {})
+    .sort(([leftName, left], [rightName, right]) => (right.total_tokens || 0) - (left.total_tokens || 0)
+      || leftName.localeCompare(rightName, "en"));
+  return {
+    total: usageRow("TOTAL", { requests: summary.requests, ...summary.totals }),
+    model_count: models.length,
+    rows: models.slice(0, 100).map(([name, values]) => usageRow(name, values)),
+  };
+}
+
+export async function handleDashboardApi(req, res, pathname, {
+  env = process.env,
+  home = os.homedir(),
+  liveModelsFn = () => fetchLiveCopilotModels({ home }),
+  usageSummaryFn = () => summarizeUsageLogs(),
+} = {}) {
+  if (!isLoopbackAddress(req.socket?.remoteAddress)
+    || req.headers?.host === undefined
+    || !isLoopbackHostHeader(req.headers.host)) {
+    sendJson(res, 403, { error: "Dashboard API is available only at a loopback address" });
+    return;
+  }
+  if (req.headers?.["x-ccdx-dashboard"] !== "1") {
+    sendJson(res, 403, { error: "Dashboard API requires a same-origin page request" });
+    return;
+  }
+
+  if (pathname === ANIMATION_PATH && req.method === "GET") {
+    try {
+      sendJson(res, 200, animationState(env, home, { includeFrames: true }));
+    } catch {
+      sendJson(res, 409, { error: "Animation settings are invalid; inspect them with ccdx animation" });
+    }
+    return;
+  }
+
+  if (pathname === ANIMATION_PATH && req.method === "POST") {
+    if (!sameOrigin(req)) {
+      sendJson(res, 403, { error: "Animation changes require the same-origin dashboard" });
+      return;
+    }
+    if (String(req.headers?.["content-type"] || "").split(";", 1)[0].trim().toLowerCase() !== "application/json") {
+      sendJson(res, 415, { error: "Animation changes require application/json" });
+      return;
+    }
+    const abort = createRequestAbort(req, res);
+    abort.setTimeout(5000, "request_body_timeout");
+    let body;
+    try {
+      body = await readJsonBody(req, { maxBodyBytes: 2048, maxDecodedBodyBytes: 2048, signal: abort.signal });
+    } catch (error) {
+      sendJson(res, error?.statusCode === 413 ? 413 : 400, { error: "Invalid animation request body" });
+      return;
+    } finally {
+      abort.cleanup();
+    }
+    if (!isTerminalAnimationTheme(body?.theme)) {
+      sendJson(res, 400, { error: "Select a listed animation theme" });
+      return;
+    }
+    try {
+      const result = writeTerminalAnimationTheme(body.theme, { env, home });
+      sendJson(res, 200, { changed: result.changed, ...animationState(env, home) });
+    } catch {
+      sendJson(res, 409, { error: "Animation setting was not saved; check ccdx animation" });
+    }
+    return;
+  }
+
+  if (pathname === MODELS_PATH && req.method === "GET") {
+    try {
+      const catalog = await liveModelsFn();
+      if (!Array.isArray(catalog?.models) || !Number.isFinite(catalog?.advertised)) {
+        throw new Error("Invalid live model catalog");
+      }
+      const models = catalog.models;
+      sendJson(res, 200, {
+        source: "live",
+        checked_at: new Date().toISOString(),
+        upstream_host: safeText(catalog?.upstreamHost || "GitHub Copilot", 120),
+        advertised: finite(catalog?.advertised),
+        selectable: models.length,
+        models: models.slice(0, 500).map((model) => ({
+          id: safeText(model.id, 100),
+          vendor: safeText(model.vendor, 80),
+          endpoints: Array.isArray(model.endpoints) ? model.endpoints.filter((value) => value === "responses" || value === "chat") : [],
+          preview: model.preview === true,
+        })),
+      });
+    } catch (error) {
+      sendJson(res, 502, { error: liveModelError(error) });
+    }
+    return;
+  }
+
+  if (pathname === USAGE_PATH && req.method === "GET") {
+    try {
+      sendJson(res, 200, { source: "local_usage_log", ...(usageTable(await usageSummaryFn())) });
+    } catch {
+      sendJson(res, 500, { error: "Could not read local usage summary" });
+    }
+    return;
+  }
+
+  sendJson(res, 405, { error: "Method not allowed" });
+}

package/src/dashboard.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { isLoopbackAddress, isLoopbackHostHeader } from "./observability.mjs";
+
+const ASSETS = new Map([
+  ["/", ["./dashboard/index.html", "text/html; charset=utf-8"]],
+  ["/ui.css", ["./dashboard/ui.css", "text/css; charset=utf-8"]],
+  ["/theme.js", ["./dashboard/theme.js", "text/javascript; charset=utf-8"]],
+  ["/ui.js", ["./dashboard/ui.js", "text/javascript; charset=utf-8"]],
+]);
+
+export async function serveDashboard(req, res, pathname) {
+  if (!isLoopbackAddress(req.socket?.remoteAddress)
+    || req.headers?.host === undefined
+    || !isLoopbackHostHeader(req.headers.host)) {
+    res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+    res.end("The CCDX dashboard is available only at a loopback address.");
+    return;
+  }
+
+  const [file, contentType] = ASSETS.get(pathname);
+  const body = await readFile(new URL(file, import.meta.url));
+  res.writeHead(200, {
+    "Content-Type": contentType,
+    "Cache-Control": "no-store",
+    "Content-Security-Policy": "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "DENY",
+    "Referrer-Policy": "no-referrer",
+  });
+  res.end(req.method === "HEAD" ? undefined : body);
+}

package/src/observability.mjs

@@ -108,6 +108,19 @@ export function isLoopbackAddress(address) {
   return isIP(ipv4) === 4 && ipv4.startsWith("127.");
 }
 
+export function isLoopbackHostHeader(host) {
+  if (host === undefined) return true; // HTTP/1.0 and in-process callers may omit Host.
+  if (typeof host !== "string" || !host || host.includes(",")) return false;
+  try {
+    const url = new URL(`http://${host}`);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    return !url.username && !url.password && url.pathname === "/" && !url.search && !url.hash
+      && (hostname === "localhost" || isLoopbackAddress(hostname));
+  } catch {
+    return false;
+  }
+}
+
 function modelRegistryStatus(modelRegistry) {
   const modelData = Array.isArray(modelRegistry?.models)
     ? modelRegistry.models