codex-copilot-dx 0.9.3 → 0.9.4

package/README.md

@@ -107,6 +107,8 @@ This performs a fresh, read-only GitHub Copilot model-directory lookup without s
 
 Interactive terminals use aligned tables for `models`, `auth status`, and `usage`. Redirected or piped output retains the plain-text layout for scripts; use `--format table` or `--format plain` when a command offers an explicit format override.
 
+`ccdx usage` and the dashboard Usage table show token cache hit rate for each model and the aggregate: cached input tokens divided by input tokens, weighted by token count rather than averaging request percentages. This describes the upstream prompt cache; the local history and image-transform caches are separate. A rate is `—` when input tokens are zero or any included record lacks valid paired input/cache counts. Older logs may omit explicit zero cache counts; new Responses usage records retain reported zeros. CLI tables keep existing token columns on narrow terminals and show rates below the table when the extra column does not fit.
+
 ### Auto-review model
 
 ```bash

package/package.json

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

package/src/dashboard/index.html

@@ -63,7 +63,8 @@
         <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>
+          <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><th scope="col">CACHE HIT</th></tr></thead><tbody id="usage-body"><tr><td colspan="7">Loading…</td></tr></tbody></table></div>
+          <p class="hint">Cache hit = cached / input tokens. — = incomplete usage data or no input tokens.</p>
         </section>
 
         <section class="lower" aria-label="Recent failures">

package/src/dashboard/ui.js

@@ -308,7 +308,9 @@ async function loadModels() {
 }
 
 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)];
+  const rate = Number.isFinite(row.cache_hit_rate) && row.cache_hit_rate >= 0 && row.cache_hit_rate <= 1
+    ? `${(row.cache_hit_rate * 100).toFixed(1)}%` : "—";
+  return [row.model, number(row.requests), number(row.input_tokens), number(row.cache_read_tokens), number(row.output_tokens), number(row.total_tokens), rate];
 }
 
 async function loadUsage() {
@@ -316,7 +318,7 @@ async function loadUsage() {
   button.disabled = true;
   text("usage-state", "READING LOG");
   text("usage-note", "Aggregating local usage metadata…");
-  emptyTable("usage-body", 6, "Loading…");
+  emptyTable("usage-body", 7, "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();
@@ -327,14 +329,14 @@ async function loadUsage() {
       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.");
+      emptyTable("usage-body", 7, "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.");
+    emptyTable("usage-body", 7, "No usage summary available.");
   } finally {
     button.disabled = false;
   }

package/src/dashboard-api.mjs

@@ -9,7 +9,7 @@ import {
   renderTerminalAnimationFrame,
   TERMINAL_ANIMATION_THEMES,
 } from "./terminal-animation.mjs";
-import { summarizeUsageLogs } from "./usage.mjs";
+import { cacheReadTokens, summarizeUsageLogs, usageCacheHitRate } from "./usage.mjs";
 import { readUserSettings, terminalAnimationPreference, writeTerminalAnimationTheme } from "./user-settings.mjs";
 
 const ANIMATION_PATH = "/_ccdx/ui/animation";
@@ -79,17 +79,13 @@ 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),
+    cache_read_tokens: cacheReadTokens(values) ?? null,
+    cache_hit_rate: usageCacheHitRate(values),
     output_tokens: finite(values.output_tokens),
     total_tokens: finite(values.total_tokens),
   };

package/src/usage.mjs

@@ -54,9 +54,10 @@ function hasPositiveTokenValue(usage) {
 
 function normalizeResponsesUsage(usage) {
   if (!usage || typeof usage !== "object") return undefined;
+  const cachedInput = numberOrUndefined(usage.cached_input_tokens ?? usage.input_tokens_details?.cached_tokens);
   const out = compactObject({
     input_tokens: positiveNumber(usage.input_tokens),
-    cached_input_tokens: positiveNumber(usage.cached_input_tokens ?? usage.input_tokens_details?.cached_tokens),
+    cached_input_tokens: cachedInput >= 0 ? cachedInput : undefined,
     output_tokens: positiveNumber(usage.output_tokens),
     reasoning_output_tokens: positiveNumber(usage.reasoning_output_tokens ?? usage.output_tokens_details?.reasoning_tokens),
     total_tokens: positiveNumber(usage.total_tokens),
@@ -251,7 +252,7 @@ export async function readUsageRecords(filePath = usageLogPath(), { warn = conso
 }
 
 function addUsageTotals(target, usage = {}) {
-  for (const [key, value] of Object.entries(usage)) {
+  for (const [key, value] of Object.entries(usage || {})) {
     if (Number.isFinite(value)) target[key] = (target[key] || 0) + value;
   }
 }
@@ -270,6 +271,12 @@ export function summarizeUsage(records) {
     const modelTotals = summary.byModel[model];
     modelTotals.requests += 1;
     addUsageTotals(modelTotals, record.usage);
+    const input = record.usage?.input_tokens;
+    const cached = cacheReadTokens(record.usage || {});
+    if (!Number.isFinite(input) || input < 0 || !Number.isFinite(cached) || cached < 0 || cached > input) {
+      summary.totals.cache_hit_unknown_requests = (summary.totals.cache_hit_unknown_requests || 0) + 1;
+      modelTotals.cache_hit_unknown_requests = (modelTotals.cache_hit_unknown_requests || 0) + 1;
+    }
   }
   return summary;
 }
@@ -298,13 +305,26 @@ function tableNumber(n) {
   return Number.isFinite(n) ? n.toLocaleString("en-US") : undefined;
 }
 
-function cacheReadTokens(usage = {}) {
+export function cacheReadTokens(usage = {}) {
   const values = [usage.cache_read_input_tokens, usage.cached_input_tokens]
     .filter((value) => Number.isFinite(value));
   const value = values.length > 0 ? values.reduce((total, current) => total + current, 0) : undefined;
   return Number.isFinite(value) ? value : undefined;
 }
 
+export function usageCacheHitRate(usage = {}) {
+  const input = usage.input_tokens;
+  const cached = cacheReadTokens(usage);
+  if (usage.cache_hit_unknown_requests > 0 || !Number.isFinite(input) || input <= 0
+    || !Number.isFinite(cached) || cached < 0 || cached > input) return null;
+  return cached / input;
+}
+
+function cacheHitPercent(usage) {
+  const rate = usageCacheHitRate(usage);
+  return rate === null ? "—" : `${(rate * 100).toFixed(1)}%`;
+}
+
 function formatPlainUsageSummary(summary, filePath, { sanitize = false } = {}) {
   const lines = [`Usage log: ${filePath}`];
   if (summary.requests === 0) {
@@ -314,11 +334,12 @@ function formatPlainUsageSummary(summary, filePath, { sanitize = false } = {}) {
   lines.push(
     `Requests: ${fmt(summary.requests)}`,
     `Tokens: input=${fmt(summary.totals.input_tokens)} cache_read=${fmt(cacheReadTokens(summary.totals))} output=${fmt(summary.totals.output_tokens)} total=${fmt(summary.totals.total_tokens)}`,
+    `Cache hit: ${cacheHitPercent(summary.totals)} (cached/input tokens)`,
     "",
     "By model:",
   );
   for (const [model, row] of Object.entries(summary.byModel)) {
-    lines.push(`  ${model}: requests=${fmt(row.requests)} input=${fmt(row.input_tokens)} cache_read=${fmt(cacheReadTokens(row))} output=${fmt(row.output_tokens)} total=${fmt(row.total_tokens)}`);
+    lines.push(`  ${model}: requests=${fmt(row.requests)} input=${fmt(row.input_tokens)} cache_read=${fmt(cacheReadTokens(row))} output=${fmt(row.output_tokens)} total=${fmt(row.total_tokens)} cache_hit=${cacheHitPercent(row)}`);
   }
   return (sanitize ? lines.map((line) => terminalCell(line, { fallback: "" })) : lines).join("\n");
 }
@@ -338,11 +359,12 @@ function usageTableRow(model, usage) {
     cacheRead: tableNumber(cacheReadTokens(usage)),
     output: tableNumber(usage.output_tokens),
     total: tableNumber(usage.total_tokens),
+    cacheHit: cacheHitPercent(usage),
   };
 }
 
 function usageDetailLine(model, usage) {
-  return `${terminalCell(model)}: input=${fmt(usage.input_tokens)} cache_read=${fmt(cacheReadTokens(usage))} output=${fmt(usage.output_tokens)}`;
+  return `${terminalCell(model)}: input=${fmt(usage.input_tokens)} cache_read=${fmt(cacheReadTokens(usage))} output=${fmt(usage.output_tokens)} cache_hit=${cacheHitPercent(usage)}`;
 }
 
 function formatTableUsageSummary(summary, filePath, output) {
@@ -362,13 +384,19 @@ function formatTableUsageSummary(summary, filePath, output) {
     .sort(compareModelUsage);
   const totalUsage = { requests: summary.requests, ...summary.totals };
   const rows = [usageTableRow("TOTAL", totalUsage), ...modelUsage.map(({ model, row }) => usageTableRow(model, row))];
-  const table = formatResponsiveCliTable({
-    columns,
-    compactColumns,
+  let table = formatResponsiveCliTable({
+    columns: [...columns, { key: "cacheHit", label: "HIT %", align: "right" }],
+    compactColumns: columns,
     rows,
     width: cliOutputWidth(output),
     gap: 1,
   });
+  const rateFits = !table.compact;
+  if (table.overflow) {
+    table = formatResponsiveCliTable({ columns, compactColumns, rows, width: cliOutputWidth(output), gap: 1 });
+  } else {
+    table.compact = false;
+  }
   const lines = [`Usage log: ${safePath}`, "", table.output];
   if (table.compact) {
     lines.push(
@@ -377,6 +405,10 @@ function formatTableUsageSummary(summary, filePath, output) {
       usageDetailLine("TOTAL", totalUsage),
       ...modelUsage.map(({ model, row }) => usageDetailLine(model, row)),
     );
+  } else if (!rateFits) {
+    lines.push("", "Cache hit (cached/input tokens):",
+      `TOTAL: ${cacheHitPercent(totalUsage)}`,
+      ...modelUsage.map(({ model, row }) => `${terminalCell(model)}: ${cacheHitPercent(row)}`));
   }
   return { output: lines.join("\n"), overflow: table.overflow };
 }