claude-token-saver 3.34.0 → 3.35.0

package/bin/cli.js

@@ -87,7 +87,7 @@ function readUpdateChip() {
 const KNOWN_SUBCOMMANDS = new Set([
   'last', 'brief', 'history', 'handoff', 'install', 'uninstall', 'mode', 'korean',
   'doc2md', 'harness', 'route-scan', 'compact-window', 'update-check', 'upgrade',
-  'seed',
+  'seed', 'litellm-budget',
 ]);
 
 const USAGE = `claude-token-saver — Claude Code token usage, cache health, and model routing
@@ -274,6 +274,32 @@ async function main() {
     });
   }
 
+  // Subcommand: litellm-budget · LiteLLM 게이트웨이 키의 max_budget/spend 조회.
+  //   claude-token-saver litellm-budget            # 캐시된 예산 상태 출력
+  //   claude-token-saver litellm-budget --refresh  # 지금 프록시에 물어봄 (detached 자식이 사용)
+  if (args[0] === 'litellm-budget') {
+    const { gatewayEnv, readBudgetState, refreshBudgetState } = await import('../src/litellm-budget.js');
+    const quiet = hasFlag('--quiet');
+    if (hasFlag('--refresh')) {
+      try {
+        const next = await refreshBudgetState();
+        if (!quiet) console.log(JSON.stringify(next, null, 2));
+      } catch (e) {
+        debug('litellm-budget:refresh', e);
+        if (!quiet) console.error(`litellm-budget refresh failed: ${e.message}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const gw = gatewayEnv();
+    if (!gw) {
+      console.log('게이트웨이가 감지되지 않았습니다 (ANTHROPIC_BASE_URL + 키 필요).');
+      return;
+    }
+    console.log(JSON.stringify(readBudgetState(), null, 2));
+    return;
+  }
+
   // Subcommand: upgrade — run the install command that matches how this copy
   // got here, then confirm the new version.
   //   claude-token-saver upgrade          # install the latest release
@@ -493,6 +519,21 @@ async function main() {
       debug('caps-cache:persist', e);
     }
   }
+  // LiteLLM 게이트웨이(Bedrock 등): stdin에 rate_limits가 아예 오지 않으므로
+  // 키의 max_budget/spend 를 cap 게이지로 대신 보여 준다. 조회는 캐시만 읽고,
+  // 갱신은 detached 자식에게 맡겨 렌더가 네트워크를 기다리지 않게 한다.
+  if (isStatusline) {
+    try {
+      const { budgetWindow, maybeSpawnBudgetCheck } = await import('../src/litellm-budget.js');
+      maybeSpawnBudgetCheck();
+      if (!caps || !Array.isArray(caps.windows) || caps.windows.length === 0) {
+        const bw = budgetWindow();
+        if (bw) caps = { windows: [bw] };
+      }
+    } catch (e) {
+      debug('litellm-budget:window', e);
+    }
+  }
   if (!isStatusline && (!caps || !model)) {
     try {
       const { loadRecentSnapshot } = await import('../src/caps-cache.js');
@@ -575,6 +616,23 @@ async function main() {
   }
   const lastActivity = Math.max(otherLastActivity, currentSessionLastUser);
 
+  // 이번 달 1일 00시 이후 지출 추정치. 통계선 기본 창(30d)이 월초를 덮으면
+  // 이미 파싱한 세션을 재사용하고, 사용자가 창을 줄여 둔 경우(mode 1d 등)에만
+  // 월초까지 다시 파싱한다. 파싱 결과는 세션 캐시가 받아 주므로 싸다.
+  let monthSpendInfo = null;
+  if (isStatusline) {
+    try {
+      const { monthSpend, monthStartMs } = await import('../src/month-spend.js');
+      const daysNeeded = (Date.now() - monthStartMs()) / 86400000;
+      const monthSessions = days >= daysNeeded
+        ? sessions
+        : await parseAllSessions({ days: Math.max(1, Math.ceil(daysNeeded)), projectFilter });
+      monthSpendInfo = monthSpend(monthSessions);
+    } catch (e) {
+      debug('month-spend', e);
+    }
+  }
+
   // What delegation has measurably saved, read straight from the registry
   // route-scan maintains. A lookup, never a scan: the statusline re-renders
   // every few seconds and a scan parses tens of MB of transcripts.
@@ -636,6 +694,7 @@ async function main() {
     // Cached-only; the background refresh it may trigger lands on a later render.
     update: format === 'statusline' ? readUpdateChip() : null,
     lastActivity,
+    monthSpend: monthSpendInfo,
     spikeReport,
     contextWindow,
     ctxLive,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/formatters/statusline.js

@@ -380,6 +380,25 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     doc2mdSeg = `${c(GRAY)}${label} ${doc2mdDocs} docs${c(RESET)}`;
   }
 
+  // 이번 달 지출 세그먼트. 달력 월(1일 00시 기준) 지출 추정치라서 cap 이 없는
+  // 게이트웨이 사용자에게도 항상 의미가 있다. 정보성 지표이므로 회색으로,
+  // 게이지들 뒤에 조용히 놓는다.
+  //   icon:    "💵 Sep $42.1"
+  //   text:    "Sep spend $42.1"
+  //   verbose: "Sep spend $42.1 (since Sep 1)"
+  const month = data.monthSpend;
+  let monthSeg = null;
+  if (month && Number(month.usd) > 0) {
+    const amt = formatMoney(Number(month.usd));
+    if (isIcon) {
+      monthSeg = `${c(GRAY)}💵 ${month.label} ${amt}${c(RESET)}`;
+    } else if (verbose) {
+      monthSeg = `${c(GRAY)}${month.label} spend ${amt} (since ${month.label} 1)${c(RESET)}`;
+    } else {
+      monthSeg = `${c(GRAY)}${month.label} spend ${amt}${c(RESET)}`;
+    }
+  }
+
   // Routing-savings headline line (multi-line layout). The lifetime sum from
   // the delegation ledger — the number the whole tool exists to grow, so it
   // gets line 1 to itself while the diagnostics move to line 2.
@@ -615,15 +634,21 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     // Icon mode renders an inline ▰▱ gauge instead of the literal "cap used" —
     // a glance at the bar conveys urgency faster than parsing a percent number,
     // and the gauge stays the same width as the percent climbs.
+    // LiteLLM 예산 윈도우는 퍼센트만으로는 감이 안 오므로(예산 크기를 모름)
+    // 금액을 함께 보여 준다: `🔑 budget ▰▱ 34% $34/$100`.
+    const money =
+      Number.isFinite(info.maxBudget) && info.maxBudget > 0
+        ? ` ${formatMoney(Number(info.spend) || 0)}/${formatMoney(info.maxBudget)}`
+        : '';
     if (isIcon) {
       const labelPart = labels.usageLabel ? `${labels.usageLabel} ` : '';
       const bar = gaugeBar(pct);
-      return `${c(tone)}${labels.icon} ${labelPart}${bar} ${pct}%${tail}${c(RESET)}`;
+      return `${c(tone)}${labels.icon} ${labelPart}${bar} ${pct}%${money}${tail}${c(RESET)}`;
     }
     if (verbose) {
-      return `${c(tone)}${labels.short} cap ${pct}% used${tail}${c(RESET)}`;
+      return `${c(tone)}${labels.short} cap ${pct}% used${money}${tail}${c(RESET)}`;
     }
-    return `${c(tone)}${labels.short} cap ${pct}%${tail}${c(RESET)}`;
+    return `${c(tone)}${labels.short} cap ${pct}%${money}${tail}${c(RESET)}`;
   }
   // Color tone: green <70%, yellow 70-89%, red 90+% (a 90+% window only
   // renders here when a *different* window won the cap-warn chip slot).
@@ -695,6 +720,7 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   for (const { key, seg } of usageSegs) {
     if (usageWant(key)) segs.push(seg);
   }
+  if (monthSeg && want('month')) segs.push(monthSeg);
   if (ctxSeg && want('ctx')) segs.push(ctxSeg);
   // Cache saved is the "lifetime brag" stat — useful but not actionable, so
   // it sits near the tail. The period label closes the line as a quiet

package/src/litellm-budget.js

@@ -0,0 +1,223 @@
+/**
+ * litellm-budget: LiteLLM 게이트웨이 사용자에게 예산 정보를 조회해 줍니다.
+ *
+ * Bedrock 등을 LiteLLM 프록시로 쓰는 환경에는 Claude Code stdin의
+ * rate_limits(5h/7d cap)가 아예 오지 않습니다. 대신 LiteLLM은 키별
+ * max_budget / spend 를 관리하므로, 그 값을 가져와 cap 게이지가 놓이던 지점에
+ * 예산 게이지를 보여 줍니다.
+ *
+ * 네트워크 호출은 update-check와 같은 모양으로 처리합니다: 렌더 경로는
+ * 캐시 파일만 읽고, 캐시가 오래되면 detached 자식 프로세스를 띄워
+ * 다음 렌더를 위해 갱신합니다. 렌더가 네트워크를 기다리는 일은 없습니다.
+ *
+ * 감지 조건: ANTHROPIC_BASE_URL 이 설정돼 있고(공식 API가 아닌 게이트웨이),
+ * 키(ANTHROPIC_AUTH_TOKEN 또는 ANTHROPIC_API_KEY)가 있을 때만 동작합니다.
+ * 엔드포인트는 LiteLLM의 `GET {base}/key/info` 이며, 호출한 키 자신의 정보를
+ * 돌려줍니다. 응답의 info.max_budget / info.spend / info.budget_reset_at 을
+ * 사용합니다. max_budget 이 null 이면(무제한 키) 게이지를 만들지 않습니다.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+import { cliEntryPath } from './update-check.js';
+import { debug } from './debug.js';
+
+// 예산은 분 단위로 변하지 않습니다. 5분이면 게이지 용도로 충분히 신선하고,
+// 통계선 렌더(수 초 간격)가 프록시를 두들기지 않습니다.
+const CHECK_INTERVAL_MS = 5 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+
+export function budgetStatePath() {
+  return join(userDataDir(), 'litellm-budget.json');
+}
+
+/** 게이트웨이 환경 정보. 감지되지 않으면 null. */
+export function gatewayEnv(env = process.env) {
+  const base = (env.ANTHROPIC_BASE_URL || '').trim().replace(/\/+$/, '');
+  if (!base) return null;
+  // 공식 엔드포인트를 그대로 가리키면 게이트웨이가 아닙니다.
+  if (/^https?:\/\/api\.anthropic\.com/i.test(base)) return null;
+  const key = (env.ANTHROPIC_AUTH_TOKEN || env.ANTHROPIC_API_KEY || '').trim();
+  if (!key) return null;
+  return { base, key };
+}
+
+export function readBudgetState() {
+  try {
+    const s = JSON.parse(readFileSync(budgetStatePath(), 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeBudgetState(next) {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(budgetStatePath(), JSON.stringify(next, null, 2) + '\n');
+}
+
+/**
+ * 렌더 경로가 쓰는 읽기 전용 접근자. 캐시된 답이 있으면
+ * rate_limits 윈도우와 같은 모양의 객체를 돌려줍니다.
+ *
+ * @returns {{key:string, usedPct:number, resetsAt:number|null,
+ *            spend:number, maxBudget:number}|null}
+ */
+export function budgetWindow(env = process.env) {
+  const gw = gatewayEnv(env);
+  if (!gw) return null;
+  const s = readBudgetState();
+  // 다른 프록시의 캐시를 재사용하지 않도록 base 단위로 격리합니다.
+  if (s.base !== gw.base) return null;
+  const max = Number(s.maxBudget);
+  const spend = Number(s.spend);
+  if (!Number.isFinite(max) || max <= 0 || !Number.isFinite(spend)) return null;
+  // 캐시에는 ms 로 저장하지만, rate_limits 윈도우의 resets_at 규약은
+  // epoch 초 단위라서 여기서 초로 맞춰 내보낸다 (formatResetClock 입력 규약).
+  const resetMs = Number(s.budgetResetAt) || null;
+  return {
+    key: 'litellm_budget',
+    usedPct: Math.min(100, Math.max(0, (spend / max) * 100)),
+    resetsAt: resetMs ? Math.round(resetMs / 1000) : null,
+    spend,
+    maxBudget: max,
+  };
+}
+
+/** 캐시가 오래됐으면 detached 자식으로 갱신을 예약합니다. 즉시 반환. */
+export function maybeSpawnBudgetCheck(env = process.env) {
+  const gw = gatewayEnv(env);
+  if (!gw) return false;
+  const s = readBudgetState();
+  const age = Date.now() - (Number(s.checkedAt) || 0);
+  if (s.base === gw.base && age < CHECK_INTERVAL_MS) return false;
+  // 오프라인/오류 시 렌더마다 자식을 다시 띄우지 않도록 시도 시각을 먼저 기록합니다.
+  try {
+    writeBudgetState({ ...s, base: gw.base, checkedAt: Date.now() });
+  } catch (e) {
+    debug('litellm-budget:stamp', e);
+    return false;
+  }
+  try {
+    spawn(process.execPath, [cliEntryPath(), 'litellm-budget', '--refresh', '--quiet'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    }).unref();
+    return true;
+  } catch (e) {
+    debug('litellm-budget:spawn', e);
+    return false;
+  }
+}
+
+function numOrNull(v) {
+  const n = Number(v);
+  return v !== null && v !== undefined && Number.isFinite(n) ? n : null;
+}
+
+function parseResetMs(v) {
+  if (!v) return null;
+  const ms = Date.parse(v);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * /key/info 와 /user/info 응답에서 예산 출처를 고릅니다 (도커 LiteLLM 실측 기준).
+ * 실무에서는 팀 멤버십 예산(LiteLLM_TeamMembership + litellm_budget_table)이
+ * 주로 쓰이므로 그쪽을 먼저 보고, 없으면 키 자체의 max_budget,
+ * 그다음 internal user 의 max_budget 순으로 내려갑니다.
+ *
+ * @returns {{source:'team'|'key'|'user', spend:number, maxBudget:number,
+ *            budgetResetAt:number|null}|null}
+ */
+export function pickBudgetSource(keyInfo, userInfo) {
+  const userId = keyInfo?.user_id ?? null;
+  const teamId = keyInfo?.team_id ?? null;
+  // ① 팀 멤버십 예산: 키의 team_id 에 해당하는 팀에서 내 user_id 의 멤버십을 찾는다.
+  const teams = Array.isArray(userInfo?.teams) ? userInfo.teams : [];
+  for (const team of teams) {
+    if (teamId && team?.team_id !== teamId) continue;
+    for (const tm of team?.team_memberships || []) {
+      if (userId && tm?.user_id !== userId) continue;
+      const max = numOrNull(tm?.litellm_budget_table?.max_budget);
+      if (max !== null && max > 0) {
+        return {
+          source: 'team',
+          spend: numOrNull(tm?.spend) ?? 0,
+          maxBudget: max,
+          budgetResetAt: parseResetMs(tm?.litellm_budget_table?.budget_reset_at),
+        };
+      }
+    }
+  }
+  // ② 키 자체 예산.
+  const keyMax = numOrNull(keyInfo?.max_budget);
+  if (keyMax !== null && keyMax > 0) {
+    return {
+      source: 'key',
+      spend: numOrNull(keyInfo?.spend) ?? 0,
+      maxBudget: keyMax,
+      budgetResetAt: parseResetMs(keyInfo?.budget_reset_at),
+    };
+  }
+  // ③ internal user 예산 (실무에서는 드물지만 폴백으로 유지).
+  const u = userInfo?.user_info;
+  const userMax = numOrNull(u?.max_budget);
+  if (userMax !== null && userMax > 0) {
+    return {
+      source: 'user',
+      spend: numOrNull(u?.spend) ?? 0,
+      maxBudget: userMax,
+      budgetResetAt: parseResetMs(u?.budget_reset_at),
+    };
+  }
+  return null;
+}
+
+/**
+ * 실제로 LiteLLM에 물어보고 캐시를 갱신합니다. detached 자식과
+ * `litellm-budget --refresh` 명령만 호출합니다.
+ * /key/info(키·소속 식별)와 /user/info(팀 멤버십 예산)를 함께 조회합니다.
+ */
+export async function refreshBudgetState(env = process.env, fetchImpl = fetch) {
+  const gw = gatewayEnv(env);
+  if (!gw) return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  const headers = {
+    accept: 'application/json',
+    authorization: `Bearer ${gw.key}`,
+  };
+  try {
+    const keyRes = await fetchImpl(`${gw.base}/key/info`, { signal: controller.signal, headers });
+    if (!keyRes.ok) throw new Error(`LiteLLM responded ${keyRes.status}`);
+    const keyBody = await keyRes.json();
+    const keyInfo = keyBody && typeof keyBody.info === 'object' ? keyBody.info : null;
+    if (!keyInfo) throw new Error('key/info response carried no info object');
+    // /user/info 는 팀 멤버십 예산 전용이라 실패해도 키 예산 폴백으로 진행한다.
+    let userInfo = null;
+    try {
+      const userRes = await fetchImpl(`${gw.base}/user/info`, { signal: controller.signal, headers });
+      if (userRes.ok) userInfo = await userRes.json();
+    } catch (e) {
+      debug('litellm-budget:user-info', e);
+    }
+    const picked = pickBudgetSource(keyInfo, userInfo);
+    const next = {
+      base: gw.base,
+      checkedAt: Date.now(),
+      source: picked ? picked.source : null,
+      spend: picked ? picked.spend : (numOrNull(keyInfo.spend) ?? 0),
+      maxBudget: picked ? picked.maxBudget : null,
+      budgetResetAt: picked ? picked.budgetResetAt : null,
+    };
+    writeBudgetState(next);
+    return next;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/month-spend.js

@@ -0,0 +1,47 @@
+/**
+ * month-spend: 이번 달 1일 00시(로컬 시각) 이후 지출한 추정 금액을 계산합니다.
+ *
+ * LiteLLM·Bedrock처럼 5h/7d cap 이 아예 없는 게이트웨이 사용자도
+ * "이번 달에 얼마나 썼는지"는 늘 궁금하므로, 세션 로그를 기반으로
+ * 달력 월 단위 지출을 통계선에 상시 노출합니다. 모델 단가는 세션마다
+ * 다르므로 세션별로 estimateCost 를 적용해 합산합니다.
+ */
+
+import { estimateCost } from './cost.js';
+
+/** 이번 달 1일 00:00(로컬)의 epoch ms. */
+export function monthStartMs(now = new Date()) {
+  return new Date(now.getFullYear(), now.getMonth(), 1).getTime();
+}
+
+/** 통계선 라벨에 쓰는 짧은 월 이름 (예: 'Sep'). */
+export function monthLabel(now = new Date()) {
+  return now.toLocaleString('en-US', { month: 'short' });
+}
+
+/**
+ * 월초 이후 세션들의 지출 추정치 합계(USD).
+ * endTime 이 월초 이후인 세션만 집계합니다. 세션이 월 경계에 걸치는
+ * 경우는 세션 전체를 포함하는데, 경계 세션은 드물고 통계선 지표는
+ * 추정치이므로 이 정도 오차는 허용합니다.
+ *
+ * @param {Array} sessions parseAllSessions 결과
+ * @param {Date} [now]
+ * @returns {{usd:number, sessions:number, sinceMs:number, label:string}}
+ */
+export function monthSpend(sessions, now = new Date()) {
+  const since = monthStartMs(now);
+  let usd = 0;
+  let count = 0;
+  for (const s of sessions || []) {
+    if (!s || !s.endTime || s.endTime.getTime() < since) continue;
+    if (!s.totals) continue;
+    try {
+      usd += estimateCost(s.totals, s.model).actual;
+      count += 1;
+    } catch {
+      // 단가를 모르는 모델은 합계에서 빠집니다. 통계선에서는 침묵이 낫습니다.
+    }
+  }
+  return { usd, sessions: count, sinceMs: since, label: monthLabel(now) };
+}

package/src/window-labels.js

@@ -23,6 +23,9 @@ const KNOWN = {
   // 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)' },
+  // LiteLLM 게이트웨이 키 예산. rate_limits 가 없는 환경에서 cap 게이지를
+  // 대신하는 합성 윈도우라서, 여기 라벨만 있으면 나머지 렌더는 공용 경로를 탄다.
+  litellm_budget: { short: 'BUDGET', long: 'LiteLLM key budget', icon: '🔑', usageLabel: 'budget' },
 };
 
 function deriveShort(key) {