claude-token-saver 2.2.0 → 2.5.0

package/src/history.js

@@ -20,6 +20,9 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+import { ISSUE_TIPS, CHIP_TO_CODES, CAP_TIPS } from './advice.js';
 
 const BASE_DIR = userDataDir();
 const HISTORY_DIR = join(BASE_DIR, 'history');
@@ -111,10 +114,56 @@ function detailKo(detail) {
   return detail;
 }
 
-function appendDayLine(en, ko, date = new Date()) {
+/**
+ * Resolve the diagnostic codes that apply to a transition. We try, in order:
+ *   1. `detail` of shape "session ID: CODE_A, CODE_B" (chip transitions with
+ *      explicit per-session codes — the richest source).
+ *   2. `chip` text mapped via CHIP_TO_CODES (covers 1M ON and chips that fire
+ *      without a per-session detail).
+ * Returns an array of unique codes, possibly empty.
+ */
+function codesForEvent(chip, detail) {
+  const out = [];
+  if (detail) {
+    const m = detail.match(/^session [^:]+:\s*(.+)$/);
+    if (m) {
+      for (const c of m[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (!out.includes(c)) out.push(c);
+      }
+    }
+  }
+  if (chip && CHIP_TO_CODES[chip]) {
+    for (const c of CHIP_TO_CODES[chip]) if (!out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Build the "💡 ..." tip block for a given chip+detail pair. Returns
+ * { en: string, ko: string } where each may be empty if no tips apply
+ * (resolution events, unknown chips, etc.).
+ */
+function tipsForEvent(chip, detail) {
+  const codes = codesForEvent(chip, detail);
+  const enLines = [];
+  const koLines = [];
+  for (const code of codes) {
+    const tip = ISSUE_TIPS[code];
+    if (!tip) continue;
+    enLines.push(`  💡 ${tip.en}`);
+    koLines.push(`  💡 ${tip.ko}`);
+  }
+  return { en: enLines.join('\n'), ko: koLines.join('\n') };
+}
+
+function appendDayLine(en, ko, date = new Date(), tips = null) {
   ensureDir(HISTORY_DIR);
   const path = join(HISTORY_DIR, `${ymd(date)}.md`);
-  const block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  // Bilingual event line. Tip lines (when present) follow on their own lines so
+  // the file reads as: event-en / └ event-ko / 💡 tip-en / 💡 tip-ko.
+  let block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  if (tips && tips.en) block += `${tips.en}\n`;
+  if (tips && tips.ko) block += `${tips.ko}\n`;
   if (!existsSync(path)) {
     const header = `# Token Monitor / 토큰 모니터 — ${ymd(date)}\n\n## Events / 이벤트\n`;
     writeFileSync(path, header + block);
@@ -143,18 +192,23 @@ export function recordChip(chip, contextHints = {}) {
   const detailKr = detail ? `  — ${detailKo(detail)}` : '';
 
   let en, ko;
+  // Tips only on warning entry/transition (not resolution) — based on the
+  // *new* chip so users see how to handle what's currently active.
+  let tips = null;
   if (current && !last) {
     en = `- ${hms(now)} ${current}${detailEn}`;
     ko = `${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
   } else if (current && last) {
     en = `- ${hms(now)} ${last} → ${current}${detailEn}`;
     ko = `${chipKo(last)} → ${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
   } else {
     // current === null, last was something — warning resolved
     en = `- ${hms(now)} ✓ resolved (was ${last})`;
     ko = `✓ 해소됨 (이전: ${chipKo(last)})`;
   }
-  appendDayLine(en, ko, now);
+  appendDayLine(en, ko, now, tips);
   saveState({ chip: current, ts: now.toISOString() });
   return true;
 }
@@ -178,53 +232,64 @@ export function readRecent(days = 7) {
   return out;
 }
 
-/**
- * Format "resets in Hh Mm" / "Mm" given a Unix-epoch resets_at value.
- * Returns null when the input isn't a finite number.
- */
-function formatResetIn(resetsAt, now = new Date()) {
-  if (!Number.isFinite(resetsAt)) return null;
-  const remainingSec = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
-  if (remainingSec <= 0) return '0m';
-  const h = Math.floor(remainingSec / 3600);
-  const m = Math.floor((remainingSec % 3600) / 60);
-  if (h > 0) return `${h}h ${m}m`;
-  return `${m}m`;
-}
-
 /**
  * Record entering or exiting the cap-warn (>=90%) zone for a rate-limit
- * window. Each window (`five_hour`, `seven_day`) has its own dedup slot, so
- * the daily file gets two transitions max per window per warning episode.
+ * window. Each window (keyed by its stdin name — e.g. `five_hour`, `seven_day`)
+ * has its own dedup slot, so the daily file gets two transitions max per
+ * window per warning episode.
  *
- * @param {'five_hour'|'seven_day'} kind
- * @param {{ usedPct: number, resetsAt: number|null } | null} info
+ * @param {{ key: string, usedPct: number, resetsAt: number|null } | null} window
  * @returns {boolean} true when a line was appended
  */
-export function recordCapTransition(kind, info) {
+export function recordCapTransition(window) {
+  if (!window || typeof window.key !== 'string') return false;
   const state = loadState();
-  const slotKey = `cap_${kind}`;
+  const slotKey = `cap_${window.key}`;
   const wasWarn = !!state[slotKey];
-  const isWarn = !!(info && Number.isFinite(info.usedPct) && info.usedPct >= 90);
+  const isWarn = Number.isFinite(window.usedPct) && window.usedPct >= 90;
   if (wasWarn === isWarn) return false;
 
   const now = new Date();
-  const labelEn = kind === 'five_hour' ? '5H' : '7D';
-  const labelKo = kind === 'five_hour' ? '5시간 윈도' : '7일 윈도';
+  const labels = labelForKey(window.key);
+  const labelEn = labels.short;
+  // Korean labels map only the well-known windows; everything else falls back
+  // to the English short label (still readable for the bilingual line).
+  const KO_OVERRIDES = {
+    five_hour: '5시간 윈도',
+    seven_day: '7일 윈도',
+    seven_day_sonnet: '7일 윈도 (Sonnet)',
+    seven_day_opus: '7일 윈도 (Opus)',
+  };
+  const labelKo = KO_OVERRIDES[window.key] || labels.short;
   let en;
   let ko;
   if (isWarn) {
-    const pct = Math.round(info.usedPct);
-    const reset = formatResetIn(info.resetsAt, now);
-    const tail = reset ? ` (resets in ${reset})` : '';
-    const tailKo = reset ? ` (리셋까지 ${reset})` : '';
+    const pct = Math.round(window.usedPct);
+    const reset = formatResetIn(window.resetsAt, now);
+    const clock = formatResetClock(window.resetsAt, now);
+    const tail = reset && clock
+      ? ` (resets in ${reset}, at ${clock})`
+      : reset
+        ? ` (resets in ${reset})`
+        : clock
+          ? ` (resets at ${clock})`
+          : '';
+    const tailKo = reset && clock
+      ? ` (${clock}에 리셋, 남은 ${reset})`
+      : reset
+        ? ` (리셋까지 ${reset})`
+        : clock
+          ? ` (${clock}에 리셋)`
+          : '';
     en = `- ${hms(now)} 🚨 ${labelEn} ${pct}% cap warning${tail}`;
     ko = `🚨 ${labelKo} ${pct}% 캡 경고${tailKo}`;
   } else {
     en = `- ${hms(now)} ✓ ${labelEn} cap warning resolved`;
     ko = `✓ ${labelKo} 캡 경고 해소`;
   }
-  appendDayLine(en, ko, now);
+  // Cap-warn entry → handoff tip; resolution → no tip (just the ✓ line).
+  const capTips = isWarn ? { en: `  💡 ${CAP_TIPS.en}`, ko: `  💡 ${CAP_TIPS.ko}` } : null;
+  appendDayLine(en, ko, now, capTips);
   state[slotKey] = isWarn;
   saveState(state);
   return true;

package/src/installer.js

@@ -39,15 +39,20 @@ countdown, savings, and (when relevant) a leading warning chip.
 
 ## What to do
 
-1. **Identify the chip.** If the user pasted a statusline, pull out the leading
-   \`⚠ ...\` chip. That maps to a specific issue category.
-2. **Show recent history.** Run \`claude-token-saver history\` (default last 7
-   days) to see the chronology of warning transitions. Each entry is timestamped
-   and includes a short detail string.
-3. **Drill down on the live state.** Run \`claude-token-saver --days 1\` (or
+1. **Lead with the most recent warning + how to handle it.** Run
+   \`claude-token-saver last\` first. It returns the most recent warning event
+   (chip + detail + timestamp) plus the full advice block for it. Surface that
+   to the user before anything else — this is what they came for.
+2. **Identify the chip.** If the user pasted a statusline (instead of relying
+   on \`last\`), pull out the leading \`⚠ ...\` chip. That maps to a specific
+   issue category.
+3. **Show recent history.** Run \`claude-token-saver history\` (default last 7
+   days) to see the chronology of warning transitions. Each entry is timestamped,
+   bilingual (English line + 한국어), and includes a \`💡\` action tip inline.
+4. **Drill down on the live state.** Run \`claude-token-saver --days 1\` (or
    another window) to render the full table view, which lists per-session
    spikes and recommended actions.
-4. **Explain the warning** in plain language. Use the chip → cause table:
+5. **Explain the warning** in plain language. Use the chip → cause table:
 
    | Chip               | Likely cause                                          |
    | ------------------ | ----------------------------------------------------- |
@@ -61,7 +66,7 @@ countdown, savings, and (when relevant) a leading warning chip.
    | \`⚠ Output heavy\`  | Output ratio dominates input — inspect long generations. |
    | \`⚠ Call surge\`    | Request count is well above baseline.                 |
 
-5. **Suggest the next action.** For \`🚨 5H/7D\` chips, recommend running
+6. **Suggest the next action.** For \`🚨 5H/7D\` chips, recommend running
    \`claude-token-saver handoff\` to back up the current work to a
    \`HANDOFF-*.md\` file before the cap hits, then continue in a fresh
    session. For 1M ON, mention \`CLAUDE_CODE_DISABLE_1M_CONTEXT=1\`. For
@@ -70,9 +75,12 @@ countdown, savings, and (when relevant) a leading warning chip.
 
 ## Useful commands
 
+- \`claude-token-saver last\` — most recent warning + full advice (start here).
+- \`claude-token-saver last --days 7\` — widen the lookback window.
 - \`claude-token-saver\` — full table report (default last 1 day).
 - \`claude-token-saver --days 7\` — wider window.
-- \`claude-token-saver history\` — recent warning transitions per day.
+- \`claude-token-saver history\` — recent warning transitions per day, with
+  inline \`💡\` action tips.
 - \`claude-token-saver history --days 30\` — longer history.
 - \`claude-token-saver handoff\` — write a HANDOFF-*.md template in cwd
   capturing git status + cap snapshot, so a fresh session can resume cleanly.
@@ -94,28 +102,31 @@ description: Show recent claude-token-saver warning history and a fresh report.
 ---
 
 You are responding to the \`/token-monitor\` slash command. The user wants a
-quick read of their Claude Code token usage and any active warnings.
+quick read of their Claude Code token usage and any active warnings — most
+importantly: **what just happened, and how do I handle it?**
 
 Steps:
 
-1. Run \`claude-token-saver history --days 7\` and capture the output. This
-   prints recent warning transitions (timestamps + chip + short detail),
-   including any \`🚨 5H NN%\` / \`🚨 7D NN%\` cap-warn entries and any
-   \`📝 handoff written: ...\` events.
-2. Run \`claude-token-saver --days 1\` and capture the output. This prints the
-   full table view: TTL breakdown, cost impact, daily trend, and any active
-   spikes with recommended actions. When a rate-limit cap is at >=90% the
-   table leads with a "🚨 Rate-limit cap is closing in" section.
-3. Summarize for the user:
-   - **Active warnings** — list the most recent unresolved chip(s) with the
-     time they appeared. Cap-warn (\`🚨 5H/7D NN%\`) outranks everything else.
-   - **Today's pattern** — when warnings cluster in time, mention it.
-   - **Recommended action** — for cap-warn, point at \`claude-token-saver
-     handoff\` so the user can back up state before the cap blocks them.
-     Otherwise pick the highest-leverage suggestion from the table report's
-     "Recommended actions" section.
-4. If the history is empty, say so plainly — no warnings means the cache has
-   been healthy and no caps were close in the configured window.
+1. **Lead with the most recent warning.** Run \`claude-token-saver last\`
+   first and surface its output verbatim (or lightly summarized) at the top
+   of your reply. This returns the latest warning event (chip + detail +
+   timestamp) followed by the full advice block. If \`last\` says no recent
+   warnings, mention that and skip ahead — you can stop here unless the user
+   asked for more.
+2. Run \`claude-token-saver history --days 7\` and capture the output. Use it
+   only to add context — e.g. "this is the 3rd cache miss today" — not to
+   re-print the whole file. Each entry is bilingual and includes a \`💡\`
+   action tip inline.
+3. Run \`claude-token-saver --days 1\` and capture the output for any extra
+   color you want to add: TTL breakdown, cost impact, daily trend, or active
+   spikes. Skip if step 1 already covered what the user needs.
+4. Summarize for the user:
+   - **What just fired** — the chip + the time + a sentence on what caused it
+     (from \`last\`).
+   - **What to do** — the action tip from \`last\`. For cap-warn (\`🚨 5H/7D NN%\`),
+     surface \`claude-token-saver handoff\` prominently so they can back up
+     state before the cap blocks them.
+   - **Today's pattern** (optional) — when warnings cluster in time, mention it.
 
 Keep the summary to ~10 lines. The user can re-run the underlying commands
 themselves for the full output.

package/src/window-labels.js

@@ -0,0 +1,61 @@
+/**
+ * Friendly labels + icons for `rate_limits.*` keys from Claude Code's stdin
+ * payload. Known keys (`five_hour`, `seven_day`) get curated short/long labels
+ * and dedicated icons. Unknown keys are passed through with a derived label so
+ * any future window Anthropic adds (e.g. `seven_day_sonnet`) renders without
+ * a code change.
+ */
+
+// `short` is used by the cap-warn chip and history records (stable shape so
+// parsers/dedup keep working). `usageLabel` is the friendlier word that the
+// always-on usage segment renders next to the icon — empty string means the
+// icon alone carries the meaning (5H 'session/now' is the implicit default).
+const KNOWN = {
+  // ✦ reads as "AI token unit" (Anthropic/OpenAI/Gemini sparkle motif), more
+  // on-theme than the 🪙 coin which suggested in-app currency. Same width as
+  // 📅 in monospace terminals so the chip alignment stays stable.
+  // 'current' mirrors how `weekly` reads next to 7D — names the window in
+  // plain English so a glance at `✦ current ████▒░ 72%` tells the eye what's
+  // being measured without parsing the icon's meaning.
+  five_hour: { short: '5H', long: 'Current session', icon: '✦', usageLabel: 'current' },
+  seven_day: { short: '7D', long: 'Current week', icon: '📅', usageLabel: 'weekly' },
+  // Speculative — `/usage` shows a Sonnet-only weekly bucket, so if Anthropic
+  // ever surfaces it on stdin we render with a sensible default already.
+  seven_day_sonnet: { short: '7D-S', long: 'Current week (Sonnet)', icon: '🅂', usageLabel: 'weekly (Sonnet)' },
+  seven_day_opus: { short: '7D-O', long: 'Current week (Opus)', icon: '🅾', usageLabel: 'weekly (Opus)' },
+};
+
+function deriveShort(key) {
+  // "five_hour" → "5H"; "seven_day_sonnet" → "7DS"; arbitrary key → uppercase initials
+  const m = key.match(/^(\d+)_?([a-z]+)/);
+  if (m) {
+    const num = m[1];
+    const word = m[2];
+    const letter = word.charAt(0).toUpperCase();
+    const tail = key.slice(m[0].length);
+    const suffix = tail
+      .split('_')
+      .filter(Boolean)
+      .map((s) => s.charAt(0).toUpperCase())
+      .join('');
+    return `${num}${letter}${suffix}`;
+  }
+  return key
+    .split('_')
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase())
+    .join('') || key;
+}
+
+function deriveLong(key) {
+  return key
+    .split('_')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+export function labelForKey(key) {
+  if (KNOWN[key]) return KNOWN[key];
+  const short = deriveShort(key);
+  return { short, long: deriveLong(key), icon: '⏱', usageLabel: short };
+}