tledger 0.2.0 → 0.3.0

package/bin/token-ledger-controls.mjs

@@ -0,0 +1,24 @@
+export const INTERACTIVE_KEY_INPUTS = Object.freeze({
+  up: Object.freeze(["\u001b[A", "k"]),
+  down: Object.freeze(["\u001b[B", "j"]),
+  quit: Object.freeze(["q", "Q", "\u0003", "\u001b"]),
+});
+
+export const INTERACTIVE_FOOTER = Object.freeze({
+  ascii: "[j/k] select   [q/Q/esc/ctrl-c] quit",
+  unicode: "[↑↓/j/k] select   [q/Q/esc/ctrl-c] quit",
+});
+
+export const INTERACTIVE_HELP = "↑/↓ or j/k move   •   q/Q, esc, or ctrl-c quit";
+
+export function actionFor(input) {
+  const value = String(input);
+  if (value.includes(INTERACTIVE_KEY_INPUTS.up[0]) || value === INTERACTIVE_KEY_INPUTS.up[1]) {
+    return "up";
+  }
+  if (value.includes(INTERACTIVE_KEY_INPUTS.down[0]) || value === INTERACTIVE_KEY_INPUTS.down[1]) {
+    return "down";
+  }
+  if (INTERACTIVE_KEY_INPUTS.quit.includes(value)) return "quit";
+  return null;
+}

package/bin/token-ledger-rates.mjs

@@ -18,10 +18,13 @@ export const RATE_CARD = {
 };
 
 export function normalizeModel(model) {
+  // Collapse underscore and whitespace separators to dashes so variants like
+  // "gpt-5.4 mini" resolve to their own rate-card entry. Keep in lockstep
+  // with normalizeModel in lib/token-ledger-importer.mjs.
   const value = String(model || "unknown")
     .trim()
     .toLowerCase()
-    .replaceAll("_", "-");
+    .replace(/[\s_]+/g, "-");
   if (RATE_CARD[value]) return value;
   if (value.startsWith("gpt-5.6-sol")) return "gpt-5.6-sol";
   if (value.startsWith("gpt-5.6-terra")) return "gpt-5.6-terra";

package/bin/token-ledger-terminal.mjs

@@ -1,7 +1,17 @@
 import {
+  eventCredits,
   normalizeQuotaTimeline,
   weeklyQuotaObservations,
 } from "./token-ledger-trend.mjs";
+import {
+  INTERACTIVE_FOOTER,
+  INTERACTIVE_HELP,
+} from "./token-ledger-controls.mjs";
+import {
+  usageBucketsInRange,
+  usageCallCount,
+  usageThreadIds,
+} from "../lib/token-ledger-usage.mjs";
 
 const RESET = "\u001b[0m";
 const PRIMARY_STYLE = [38, 2, 255, 255, 255];
@@ -74,12 +84,18 @@ function compact(value) {
     [1_000_000, "M"],
     [1_000, "K"],
   ];
-  for (const [divisor, suffix] of units) {
-    if (absolute >= divisor) {
-      const scaled = value / divisor;
-      const precision = scaled >= 100 ? 0 : scaled >= 10 ? 1 : 2;
-      return `${scaled.toFixed(precision)}${suffix}`;
+  for (let index = 0; index < units.length; index += 1) {
+    const [divisor, suffix] = units[index];
+    if (absolute < divisor) continue;
+    const scaled = value / divisor;
+    const magnitude = Math.abs(scaled);
+    const precision = magnitude >= 100 ? 0 : magnitude >= 10 ? 1 : 2;
+    // Values that round to 1000 of a unit belong to the next unit up
+    // (999,999 → 1.00M, not 1000K).
+    if (index > 0 && Number(magnitude.toFixed(precision)) >= 1_000) {
+      return compact(Math.sign(value) * divisor * 1_000);
     }
+    return `${scaled.toFixed(precision)}${suffix}`;
   }
   return Math.round(value).toLocaleString("en-US");
 }
@@ -127,7 +143,13 @@ function displayProject(row) {
   return row.displayProject || row.project || "Unlabelled activity";
 }
 
-function dateLabel(bounds, range = "day") {
+function isRollingRange(range) {
+  return range === "rolling24h" || range === "rolling";
+}
+
+function dateLabel(bounds, range = "day", rollingLabel = "1 day") {
+  if (range === "rolling24h") return "LAST 24 HOURS";
+  if (range === "rolling") return `LAST ${rollingLabel.toUpperCase()}`;
   if (range === "week" && bounds.startDateString && bounds.endDateString) {
     const startParts = bounds.startDateString.split("-").map(Number);
     const endParts = bounds.endDateString.split("-").map(Number);
@@ -227,30 +249,52 @@ export function quotaCycleSummary(snapshot = {}, displayedEvents = []) {
     };
   }
 
-  const inObservedCycle = (event) => {
-    const eventMs = new Date(event.timestamp).getTime();
-    return (
-      Number.isFinite(eventMs) &&
-      eventMs >= windowStartMs &&
-      eventMs <= observedThroughMs
+  const sumUsage = (events) =>
+    events.reduce(
+      (acc, event) => {
+        const tokens = Number(event.totalTokens) || 0;
+        acc.tokens += tokens;
+        const credits = eventCredits(event);
+        if (Number.isFinite(credits) && credits >= 0) {
+          acc.credits += credits;
+          acc.ratedTokens += tokens;
+        }
+        return acc;
+      },
+      { tokens: 0, credits: 0, ratedTokens: 0 },
     );
-  };
-  const sumTokens = (events) =>
-    events.reduce((sum, event) => sum + (Number(event.totalTokens) || 0), 0);
-  const cycleTokens = sumTokens((snapshot.events ?? []).filter(inObservedCycle));
-  const displayedTokens = sumTokens(displayedEvents.filter(inObservedCycle));
+  const cycleEndMs = observedThroughMs + 1;
+  const cycle = sumUsage(
+    usageBucketsInRange(snapshot, windowStartMs, cycleEndMs),
+  );
+  const displayed = sumUsage(
+    usageBucketsInRange(
+      { events: displayedEvents },
+      windowStartMs,
+      cycleEndMs,
+    ),
+  );
   const usedPercent = Math.min(100, Math.max(0, Number(observation.usedPercent) || 0));
-  const displayedSharePercent = cycleTokens
-    ? (displayedTokens / cycleTokens) * 100
-    : null;
+  // The weekly meter weights usage by model, token type, and fast mode;
+  // rate-card credits carry those weights. Allocate burn by credit share
+  // when every event in the cycle is rated, and fall back to raw token
+  // share otherwise.
+  const creditsUsable =
+    cycle.tokens > 0 && cycle.ratedTokens === cycle.tokens && cycle.credits > 0;
+  const displayedSharePercent = creditsUsable
+    ? (displayed.credits / cycle.credits) * 100
+    : cycle.tokens
+      ? (displayed.tokens / cycle.tokens) * 100
+      : null;
 
   return {
     available: true,
     usedPercent,
     remainingPercent: 100 - usedPercent,
-    cycleTokens,
-    displayedTokens,
+    cycleTokens: cycle.tokens,
+    displayedTokens: displayed.tokens,
     displayedSharePercent,
+    shareBasis: creditsUsable ? "credits" : "tokens",
     estimatedDisplayedBurnPercent:
       displayedSharePercent === null
         ? null
@@ -263,8 +307,13 @@ function summary(events) {
     (sum, event) => sum + (Number(event.totalTokens) || 0),
     0,
   );
-  const calls = events.length;
-  const threadIds = new Set(events.map((event) => event.threadId).filter(Boolean));
+  const calls = events.reduce(
+    (sum, event) => sum + usageCallCount(event),
+    0,
+  );
+  const threadIds = new Set(
+    events.flatMap((event) => usageThreadIds(event)),
+  );
   const outputTokens = events.reduce(
     (sum, event) => sum + (Number(event.outputTokens) || 0),
     0,
@@ -496,10 +545,28 @@ function panel(leftLines, rightLines, leftWidth, rightWidth, enabled, ascii) {
   return [top, ...body, bottom];
 }
 
-function headerLines(stats, bounds, frameWidth, options, enabled) {
+function snapshotLine(freshness, enabled) {
+  const detail = freshness?.status === "fresh" || freshness?.status === "stale"
+    ? `${freshness.status} · ${freshness.ageLabel}`
+    : "age unknown";
+  return `${colorize("SNAPSHOT", ACCENT_STYLE, enabled)} ${colorize("·", SECONDARY_STYLE, enabled)} ${colorize(detail, SECONDARY_STYLE, enabled)}`;
+}
+
+function headerLines(stats, bounds, frameWidth, options, enabled, freshness) {
   const left = colorize("TOKEN LEDGER", TITLE_STYLE, enabled);
-  const date = colorize(dateLabel(bounds, options.range), TEXT_STYLE, enabled);
-  const mode = colorize(options.range === "week" ? "7 DAYS" : "DAY", [1, ...ACCENT_STYLE], enabled);
+  const date = colorize(
+    dateLabel(bounds, options.range, options.rollingLabel),
+    TEXT_STYLE,
+    enabled,
+  );
+  const modeLabel = options.range === "rolling24h"
+    ? "24 HOURS"
+    : options.range === "rolling"
+      ? options.rollingLabel.toUpperCase()
+    : options.range === "week"
+      ? "7 DAYS"
+      : "DAY";
+  const mode = colorize(modeLabel, [1, ...ACCENT_STYLE], enabled);
   const metric = (value, label) =>
     `${colorize(String(value), TITLE_STYLE, enabled)} ${colorize(label, SECONDARY_STYLE, enabled)}`;
   const separator = colorize("·", SECONDARY_STYLE, enabled);
@@ -515,13 +582,21 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     metric(stats.projectCount.toLocaleString("en-US"), "PROJECTS"),
   ].join(join);
   if (visibleLength(fullLine) < frameWidth) {
-    return [alignHeader(fullLine)];
+    const lines = [alignHeader(fullLine)];
+    if (isRollingRange(options.range)) lines.push(alignHeader(snapshotLine(freshness, enabled)));
+    return lines;
   }
 
-  const compactDate = dateLabel(bounds, options.range)
+  const compactDate = dateLabel(bounds, options.range, options.rollingLabel)
     .replace(/ 20\d{2}$/, "")
     .replace(" – ", "–");
-  const compactMode = options.range === "week" ? "7D" : "DAY";
+  const compactMode = options.range === "rolling24h"
+    ? "24H"
+    : options.range === "rolling"
+      ? `${options.rollingAmount}${options.rollingUnit.toUpperCase()}`
+    : options.range === "week"
+      ? "7D"
+      : "DAY";
   const compactLine = [
     left,
     colorize(compactDate, TEXT_STYLE, enabled),
@@ -532,7 +607,9 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     metric(stats.projectCount.toLocaleString("en-US"), "P"),
   ].join(join);
   if (visibleLength(compactLine) < frameWidth) {
-    return [alignHeader(compactLine)];
+    const lines = [alignHeader(compactLine)];
+    if (isRollingRange(options.range)) lines.push(alignHeader(snapshotLine(freshness, enabled)));
+    return lines;
   }
 
   const minimalTitle = colorize(frameWidth >= 45 ? "LEDGER" : "L", TITLE_STYLE, enabled);
@@ -545,10 +622,20 @@ function headerLines(stats, bounds, frameWidth, options, enabled) {
     compact(stats.threads),
     compact(stats.projectCount),
   ].join(" ");
-  return [alignHeader(minimalLine)];
+  const lines = [alignHeader(minimalLine)];
+  if (isRollingRange(options.range)) lines.push(alignHeader(snapshotLine(freshness, enabled)));
+  return lines;
 }
 
-export function renderTerminal({ options, snapshot, bounds, events, rows, allRows }) {
+export function renderTerminal({
+  options,
+  snapshot,
+  snapshotFreshness,
+  bounds,
+  events,
+  rows,
+  allRows,
+}) {
   const enabled = colorsEnabled(options);
   const stats = summary(events);
   const quota = quotaCycleSummary(snapshot, events);
@@ -561,19 +648,25 @@ export function renderTerminal({ options, snapshot, bounds, events, rows, allRow
   const left = panelLines(rows, allRows, stats.totalTokens, leftWidth, options, enabled);
   const right = sideBySide ? sidebarLines(stats, sideWidth, enabled, options, quota) : null;
   const lines = [
-    ...headerLines(stats, bounds, frameWidth, options, enabled),
+    ...headerLines(stats, bounds, frameWidth, options, enabled, snapshotFreshness),
     ...panel(left, right, leftWidth, sideWidth, enabled, options.ascii),
   ];
   if (!sideBySide) {
     lines.push("");
     lines.push(...sidebarLines(stats, frameWidth, enabled, options, quota));
   }
+  if (events.some((event) => event.rangeAllocationEstimated === true)) {
+    lines.push("");
+    lines.push(colorize(
+      "≈ Boundary-spanning compact history is allocated proportionally.",
+      SECONDARY_STYLE,
+      enabled,
+    ));
+  }
   lines.push("");
   lines.push(
     colorize(
-      options.ascii
-        ? "[j/k] select   [enter] inspect   [d/w/m] range   [q] quit"
-        : "[↑↓] select   [enter] inspect   [d/w/m] range   [q] quit",
+      options.ascii ? INTERACTIVE_FOOTER.ascii : INTERACTIVE_FOOTER.unicode,
       SECONDARY_STYLE,
       enabled,
     ),
@@ -591,7 +684,17 @@ function paintFullscreenLine(line, width, background, enabled) {
   return `${background}${restored}${RESET}`;
 }
 
-export function renderFullscreen({ options, snapshot, bounds, events, rows, allRows, width, height }) {
+export function renderFullscreen({
+  options,
+  snapshot,
+  snapshotFreshness,
+  bounds,
+  events,
+  rows,
+  allRows,
+  width,
+  height,
+}) {
   const enabled = options.forceColor ?? colorsEnabled(options);
   const columns = Math.max(40, Number(width) || Number(process.stdout.columns) || 120);
   const screenHeight = Math.max(1, Number(height) || Number(process.stdout.rows) || 32);
@@ -606,6 +709,7 @@ export function renderFullscreen({ options, snapshot, bounds, events, rows, allR
       width: frameWidth + 2,
     },
     snapshot,
+    snapshotFreshness,
     bounds,
     events,
     rows,
@@ -615,7 +719,7 @@ export function renderFullscreen({ options, snapshot, bounds, events, rows, allR
   staticLines.pop();
   if (staticLines.at(-1) === "") staticLines.pop();
   const summaryLine = staticLines.shift() ?? "";
-  const help = colorize("↑/↓ move   •   j/k move   •   q/esc quit", SECONDARY_STYLE, enabled);
+  const help = colorize(INTERACTIVE_HELP, SECONDARY_STYLE, enabled);
   const content = [
     { line: summaryLine, background: SCREEN_BASE },
     ...staticLines.map((line) => ({ line, background: PANEL_BASE })),