usage-cli 0.33.5__tar.gz → 0.33.7__tar.gz

{usage_cli-0.33.5/usage_cli.egg-info → usage_cli-0.33.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usage-cli
-Version: 0.33.5
+Version: 0.33.7
 Summary: usage — 在 macOS menu bar 與 Windows 系統匣顯示 Claude Code、Codex、Antigravity 用量的小工具（也提供終端機 TUI）
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.13
@@ -274,6 +274,7 @@ If the menu bar shows `--`, it's usually not broken — there's just no local da
 - **Antigravity**, only if you use it, needs network access: quota is fetched from Google's official quota endpoint with the OAuth credential the Antigravity CLI already stored after sign-in — read from macOS Keychain, Windows Credential Manager, or a local token file depending on CLI version. `usage` never writes that credential back and keeps any refreshed access token in memory only; the call itself reads quota metadata.
 - **Other background network activity:** Public Claude and Codex status pages to flag outages, a public model-pricing table to estimate cost (built-in prices are used offline), and an occasional GitHub check for a new version.
 - **Beginner Mode**, only if you turn it on, sends Claude Code's latest answer to Claude Haiku through your own Claude Code sign-in to pick terms. Your term list stays in `~/.usage/glossary.json`.
+- **Long-term history:** Claude Code deletes transcripts older than 30 days by default. While the app runs, `usage` saves daily totals to `~/.usage/usage_snapshot.json` and `~/.usage/year_ledger.json` every 6 hours, so reports keep older days. Nothing leaves your machine. When you move to a new computer, copy the whole `~/.usage/` folder too.
 
 <details>
 <summary>How Claude Desktop quota is read</summary>

{usage_cli-0.33.5 → usage_cli-0.33.7}/README.md

@@ -252,6 +252,7 @@ If the menu bar shows `--`, it's usually not broken — there's just no local da
 - **Antigravity**, only if you use it, needs network access: quota is fetched from Google's official quota endpoint with the OAuth credential the Antigravity CLI already stored after sign-in — read from macOS Keychain, Windows Credential Manager, or a local token file depending on CLI version. `usage` never writes that credential back and keeps any refreshed access token in memory only; the call itself reads quota metadata.
 - **Other background network activity:** Public Claude and Codex status pages to flag outages, a public model-pricing table to estimate cost (built-in prices are used offline), and an occasional GitHub check for a new version.
 - **Beginner Mode**, only if you turn it on, sends Claude Code's latest answer to Claude Haiku through your own Claude Code sign-in to pick terms. Your term list stays in `~/.usage/glossary.json`.
+- **Long-term history:** Claude Code deletes transcripts older than 30 days by default. While the app runs, `usage` saves daily totals to `~/.usage/usage_snapshot.json` and `~/.usage/year_ledger.json` every 6 hours, so reports keep older days. Nothing leaves your machine. When you move to a new computer, copy the whole `~/.usage/` folder too.
 
 <details>
 <summary>How Claude Desktop quota is read</summary>

usage_cli-0.33.7/analyzer/history_persist.py

@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Periodically preserve real usage without scanning on the app thread."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from adapters.registry import detect_agents
+from analyzer import diagnosis_snapshot, reporter, usage_snapshot
+from usage_common.time_utils import parse_optional_iso8601_utc
+
+STATE_PATH = Path.home() / ".usage" / "history_persist_state.json"
+_INTERVAL = timedelta(hours=6)
+_LOOKBACK_DAYS = 45
+_lock = threading.Lock()
+_refresh_in_flight = False
+_timer: threading.Timer | None = None
+logger = logging.getLogger(__name__)
+
+
+def _remaining(now: datetime) -> float:
+    try:
+        state = json.loads(STATE_PATH.read_text(encoding="utf-8"))
+        last = (
+            parse_optional_iso8601_utc(state.get("last_success"))
+            if isinstance(state, dict)
+            else None
+        )
+    except (OSError, ValueError):
+        last = None
+    return max(0.0, (_INTERVAL - (now - last)).total_seconds()) if last else 0.0
+
+
+def _schedule_next_locked(delay: float) -> None:
+    global _timer
+    if _timer is None:
+        _timer = threading.Timer(delay, _on_timer)
+        _timer.daemon = True
+        try:
+            _timer.start()
+        except Exception:
+            _timer = None
+            raise
+
+
+def _on_timer() -> None:
+    global _timer
+    with _lock:
+        _timer = None
+    maybe_schedule_refresh()
+
+
+def maybe_schedule_refresh() -> None:
+    global _refresh_in_flight, _timer
+    try:
+        with _lock:
+            if _refresh_in_flight:
+                return
+            remaining = _remaining(datetime.now(UTC))
+            if remaining > 0:
+                _schedule_next_locked(remaining)
+                return
+            if _timer is not None:
+                _timer.cancel()
+                _timer = None
+            _refresh_in_flight = True
+        threading.Thread(target=_refresh_in_background, daemon=True).start()
+    except Exception:
+        with _lock:
+            _refresh_in_flight = False
+        logger.warning("Failed to schedule usage history persistence", exc_info=True)
+
+
+def _refresh_in_background() -> None:
+    global _refresh_in_flight
+    try:
+        refresh_history()
+    except Exception:
+        logger.warning("Failed to persist usage history", exc_info=True)
+    finally:
+        with _lock:
+            _refresh_in_flight = False
+            try:
+                _schedule_next_locked(_INTERVAL.total_seconds())
+            except Exception:
+                logger.warning("Failed to reschedule usage history persistence", exc_info=True)
+
+
+def refresh_history(now: datetime | None = None) -> bool:
+    current = now or datetime.now(UTC)
+    if _remaining(current) > 0:
+        return False
+    today = current.astimezone().date()
+    entries = reporter.load_history_entries(
+        detect_agents(), today - timedelta(days=_LOOKBACK_DAYS - 1), today
+    )
+    snapshot = usage_snapshot.record_entries(entries)
+    ledger = reporter.persist_year_entries(entries, today)
+    # Existing writers swallow I/O errors. Read back before marking success.
+    for path, expected in (
+        (usage_snapshot.SNAPSHOT_PATH, snapshot),
+        (reporter.YEAR_LEDGER_PATH, ledger),
+    ):
+        if json.loads(path.read_text(encoding="utf-8")) != expected:
+            raise OSError(f"Usage history write verification failed: {path}")
+    diagnosis_snapshot._atomic_write_json(STATE_PATH, {"last_success": current.isoformat()})
+    return True

usage_cli-0.33.7/analyzer/ledger_backfill.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 lollapalooza <https://github.com/aqua5230>
+#
+# Part of "usage". Free software licensed under the GNU Affero General Public
+# License v3.0 only; see the LICENSE file for full terms and the warranty disclaimer.
+
+"""Rehydrate only the daily token gap left after snapshot replay."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Mapping, Sequence
+from datetime import date, datetime
+from typing import TYPE_CHECKING
+
+from adapters.types import UsageEntry
+from usage_common.pricing import calculate_cost
+
+if TYPE_CHECKING:
+    from analyzer.reporter import _YearDay
+
+
+def is_ledger_entry(entry: UsageEntry) -> bool:
+    return entry.session_id.startswith("usage-ledger:")
+
+
+def _allocate(
+    ledger: Mapping[str, int], current: Mapping[str, int], gap: int
+) -> list[tuple[str, int]]:
+    weights = {key: max(tokens - current.get(key, 0), 0) for key, tokens in ledger.items()}
+    if not any(weights.values()):
+        weights = {key: max(tokens, 0) for key, tokens in ledger.items()}
+    total = sum(weights.values())
+    if total == 0:
+        return [("unknown", gap)]
+    # Integer largest-remainder allocation keeps every dimension's sum exact.
+    shares = {key: gap * weight // total for key, weight in weights.items()}
+    ranked = sorted(weights, key=lambda key: (-(gap * weights[key] % total), key))
+    for key in ranked[: gap - sum(shares.values())]:
+        shares[key] += 1
+    return [(key, shares[key]) for key in sorted(shares) if shares[key] > 0]
+
+
+def merge_with_ledger(
+    entries: Sequence[UsageEntry],
+    entry_dates: Mapping[int, date],
+    days: Mapping[str, _YearDay],
+    date_from: date,
+    date_to: date,
+) -> tuple[list[UsageEntry], dict[int, date]]:
+    merged = list(entries)
+    dates = dict(entry_dates)
+    by_day: dict[date, list[UsageEntry]] = defaultdict(list)
+    for entry in entries:
+        by_day[entry_dates[id(entry)]].append(entry)
+    for day_key, ledger in sorted(days.items()):
+        day = date.fromisoformat(day_key)
+        if not date_from <= day <= date_to or not any(
+            tokens > 0 for tokens in ledger["agent_tokens"].values()
+        ):
+            continue
+        current = by_day.get(day, [])
+        gap = ledger["total_tokens"] - sum(entry.total_tokens for entry in current)
+        if gap <= 0:
+            continue
+        dimensions: list[list[tuple[str, int]]] = []
+        for attribute, ledger_tokens in (
+            ("agent_id", ledger["agent_tokens"]),
+            ("project", ledger["project_tokens"]),
+            ("model", ledger["model_tokens"]),
+        ):
+            totals: dict[str, int] = defaultdict(int)
+            for entry in current:
+                totals[getattr(entry, attribute) or "unknown"] += entry.total_tokens
+            dimensions.append(_allocate(ledger_tokens, totals, gap))
+        cost_gap = max(ledger["cost"] - sum(calculate_cost(entry) for entry in current), 0.0)
+        # Intersect the three allocations without claiming historical correlations.
+        indices = [0, 0, 0]
+        remaining = [dimension[0][1] for dimension in dimensions]
+        allocated = 0
+        while allocated < gap:
+            tokens = min(remaining)
+            agent, project, model = (
+                dimension[index][0] for dimension, index in zip(dimensions, indices, strict=True)
+            )
+            synthetic_id = f"usage-ledger:{day_key}:{allocated}"
+            entry = UsageEntry(
+                timestamp=datetime.combine(day, datetime.min.time()),
+                session_id=f"usage-ledger:{day_key}",
+                message_id=synthetic_id,
+                request_id=synthetic_id,
+                agent_id=agent,
+                project=project,
+                model=model,
+                input_tokens=tokens,
+                output_tokens=0,
+                cache_creation_tokens=0,
+                cache_read_tokens=0,
+                cost_usd=cost_gap * tokens / gap,
+                message_count=0,
+            )
+            merged.append(entry)
+            dates[id(entry)] = day
+            allocated += tokens
+            for axis in range(3):
+                remaining[axis] -= tokens
+                if remaining[axis] == 0 and allocated < gap:
+                    indices[axis] += 1
+                    remaining[axis] = dimensions[axis][indices[axis]][1]
+    return merged, dates

{usage_cli-0.33.5 → usage_cli-0.33.7}/analyzer/reporter.py

@@ -27,7 +27,7 @@ from adapters.types import AgentInfo, UsageEntry
 from usage_common.pricing import calculate_cost, is_model_priced
 
 from .aggregator import aggregate_sessions
-from . import diagnoser, dispatch_ledger, usage_snapshot
+from . import diagnoser, dispatch_ledger, ledger_backfill, usage_snapshot
 
 logger = logging.getLogger(__name__)
 
@@ -317,6 +317,18 @@ def _load_agent_entries(
     return entries
 
 
+def load_history_entries(
+    agents: list[AgentInfo], date_from: date, date_to: date
+) -> list[UsageEntry]:
+    hours_back = ((date_to - date_from).days + 2) * 24
+    return [
+        entry
+        for agent in agents
+        for entry in _load_agent_entries(agent, hours_back)
+        if date_from <= _entry_date(entry) <= date_to and not ledger_backfill.is_ledger_entry(entry)
+    ]
+
+
 def _load_recent_claude_entries(hours_back: int) -> list[UsageEntry]:
     entries: list[UsageEntry] = []
     seen: set[str] = set()
@@ -798,6 +810,15 @@ def build_year_data(agents: list[AgentInfo]) -> YearReportData:
     )
 
 
+def persist_year_entries(entries: list[UsageEntry], today: date) -> _YearLedger:
+    grid_end = today + timedelta(days=(5 - today.weekday()) % 7)
+    grid_start = grid_end - timedelta(days=_YEAR_WEEKS * 7 - 1)
+    return _merge_year_ledger(
+        _aggregate_year_days(entries),
+        trim_before=grid_start - timedelta(days=_YEAR_LEDGER_TRIM_BUFFER_DAYS),
+    )
+
+
 def _load_year_data_cached(agents: list[AgentInfo]) -> YearReportData:
     cached = _read_year_cache()
     if cached is not None:
@@ -923,10 +944,21 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         raw_entries.extend(_load_agent_entries(agent, hours_back))
     entry_dates = {id(entry): _entry_date(entry) for entry in raw_entries}
 
+    ledger_days = _read_year_ledger()["days"]
     if date_from is None:
         earliest_live = min(entry_dates.values()) if entry_dates else None
         earliest_snap = usage_snapshot.earliest_date()
-        earliest_candidates = [day for day in (earliest_live, earliest_snap) if day is not None]
+        earliest_ledger = min(
+            (
+                date.fromisoformat(day)
+                for day, value in ledger_days.items()
+                if any(tokens > 0 for tokens in value["agent_tokens"].values())
+            ),
+            default=None,
+        )
+        earliest_candidates = [
+            day for day in (earliest_live, earliest_snap, earliest_ledger) if day is not None
+        ]
         date_from = min(earliest_candidates) if earliest_candidates else date_to
 
     span_from = date_from
@@ -940,12 +972,16 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
     raw_entries, entry_dates = usage_snapshot.merge_live_with_snapshot(
         raw_entries, entry_dates, span_from, span_to
     )
+    raw_entries, entry_dates = ledger_backfill.merge_with_ledger(
+        raw_entries, entry_dates, ledger_days, span_from, span_to
+    )
 
     entries = [entry for entry in raw_entries if date_from <= entry_dates[id(entry)] <= date_to]
 
+    real_entries = [entry for entry in entries if not ledger_backfill.is_ledger_entry(entry)]
     total_tokens = sum(entry.total_tokens for entry in entries)
     total_cost = 0.0
-    session_ids = {entry.session_id for entry in entries}
+    session_ids = {entry.session_id for entry in real_entries}
     active_dates = {entry_dates[id(entry)] for entry in entries}
     total_days = (date_to - date_from).days + 1
     comparison = _build_comparison(raw_entries, entry_dates, period, date_from, date_to)
@@ -974,7 +1010,7 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         lambda: defaultdict(lambda: defaultdict(int))
     )
     daily_totals: dict[date, dict[str, Any]] = defaultdict(lambda: {"tokens": 0, "cost": 0.0})
-    cube_totals: dict[tuple[date, str, str, str], dict[str, int | float]] = defaultdict(
+    cube_totals: dict[tuple[date, str, str, str, bool], dict[str, int | float]] = defaultdict(
         lambda: {
             "input_tokens": 0,
             "output_tokens": 0,
@@ -990,18 +1026,20 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         total_cost += cost
         agent_totals = by_agent_totals[entry.agent_id or "unknown"]
         agent_totals["tokens"] += entry.total_tokens
-        agent_totals["input_tokens"] += entry.input_tokens
-        agent_totals["output_tokens"] += entry.output_tokens
-        agent_totals["cache_creation_tokens"] += entry.cache_creation_tokens
-        agent_totals["cache_read_tokens"] += entry.cache_read_tokens
+        if not ledger_backfill.is_ledger_entry(entry):
+            agent_totals["input_tokens"] += entry.input_tokens
+            agent_totals["output_tokens"] += entry.output_tokens
+            agent_totals["cache_creation_tokens"] += entry.cache_creation_tokens
+            agent_totals["cache_read_tokens"] += entry.cache_read_tokens
+            agent_totals["sessions"].add(entry.session_id)
         agent_totals["cost"] += cost
-        agent_totals["sessions"].add(entry.session_id)
         agent_totals["messages"] += entry.message_count
 
         project = by_project_totals[entry.project or "unknown"]
         project["tokens"] += entry.total_tokens
         project["cost"] += cost
-        project["sessions"].add(entry.session_id)
+        if not ledger_backfill.is_ledger_entry(entry):
+            project["sessions"].add(entry.session_id)
 
         model = by_model_totals[entry.model or "unknown"]
         model["tokens"] += entry.total_tokens
@@ -1026,6 +1064,7 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
                 entry.agent_id or "unknown",
                 entry.model or "unknown",
                 entry.project or "unknown",
+                ledger_backfill.is_ledger_entry(entry),
             )
         ]
         cube_row["input_tokens"] += entry.input_tokens
@@ -1118,6 +1157,7 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         cube_agent_id,
         cube_model_name,
         cube_project_name,
+        _cube_is_ledger,
     ), values in cube_totals.items():
         row_tokens = (
             int(values["input_tokens"])
@@ -1162,6 +1202,7 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         cube_agent_id,
         cube_model_name,
         cube_project_name,
+        cube_is_ledger,
     ), values in cube_totals.items():
         cube_rows.append(
             [
@@ -1175,6 +1216,8 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
                 int(values["cache_read_tokens"]),
                 _round_cost(float(values["cost"])),
                 int(values["message_count"]),
+                # Optional index 10 marks ledger totals; legacy real rows stay unchanged.
+                *([1] if cube_is_ledger else []),
             ]
         )
     cube_rows.sort(key=lambda row: (row[0], row[1], row[2], row[3]))
@@ -1202,10 +1245,13 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
     top_sessions: list[TopSessionReportRow] = []
     now = datetime.now().astimezone(timezone.utc)
     weekly_entries = raw_entries if weekly_preloaded is None else weekly_preloaded
+    weekly_entries = [
+        entry for entry in weekly_entries if not ledger_backfill.is_ledger_entry(entry)
+    ]
     windows = dispatch_ledger.load_windows() if weekly_entries else {}
     estimates = dispatch_ledger.estimate_sessions(weekly_entries, windows, now)
     sessions_by_cost = sorted(
-        aggregate_sessions(entries), key=lambda session: session.cost_usd, reverse=True
+        aggregate_sessions(real_entries), key=lambda session: session.cost_usd, reverse=True
     )
     sessions_by_tokens = sorted(
         sessions_by_cost, key=lambda session: session.total_tokens, reverse=True
@@ -1238,7 +1284,7 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         )
 
     year_data = _load_year_data_cached(agents)
-    usage_snapshot.record_entries(entries, entry_dates=entry_dates)
+    usage_snapshot.record_entries(real_entries, entry_dates=entry_dates)
 
     return {
         "period": period,
@@ -1247,10 +1293,10 @@ def build_report_data(agents: list[AgentInfo], period: str = "month") -> ReportD
         "date_to": date_to.isoformat(),
         "summary": {
             "total_tokens": total_tokens,
-            "input_tokens": sum(entry.input_tokens for entry in entries),
-            "output_tokens": sum(entry.output_tokens for entry in entries),
-            "cache_creation_tokens": sum(entry.cache_creation_tokens for entry in entries),
-            "cache_read_tokens": sum(entry.cache_read_tokens for entry in entries),
+            "input_tokens": sum(entry.input_tokens for entry in real_entries),
+            "output_tokens": sum(entry.output_tokens for entry in real_entries),
+            "cache_creation_tokens": sum(entry.cache_creation_tokens for entry in real_entries),
+            "cache_read_tokens": sum(entry.cache_read_tokens for entry in real_entries),
             "cost_usd": _round_cost(total_cost),
             "sessions": len(session_ids),
             # by_project 只留前 10 名，敘述句要報真實專案數就得另外帶

{usage_cli-0.33.5 → usage_cli-0.33.7}/i18n.json

@@ -260,8 +260,8 @@
     "report_fixed_range": "固定區間",
     "report_fixed_group_note": "以下區塊不受上方日期篩選影響",
     "report_model": "模型",
-    "report_appendix_title": "數字怎麼算的",
-    "report_appendix_desc": "Token 組成 · 快取命中率 · 花費可信度",
+    "report_appendix_title": "花費怎麼算的",
+    "report_appendix_desc": "公開 API 價目換算 · 花費可信度",
     "report_narrative": "過去這段時間你燒了 {tokens} tokens。{peak_date} 是高峰（{peak_tokens}/天），主力 LLM 是 {top_model}。",
     "report_period": "區間",
     "report_project": "專案",
@@ -270,7 +270,7 @@
     "report_persona_active_hours": "活躍時段",
     "report_persona_caption": "你最常在 {h1}{h2} 與 AI 協作",
     "report_persona_caption_second": " 和 {h2}",
-    "report_persona_peak": "峰值 {count} 則",
+    "report_persona_peak": "峰值 {count} 則訊息（含工具呼叫）",
     "report_persona_empty": "這段期間還沒有足夠資料",
     "report_recent_titles_heading": "最近在做什麼",
     "report_persona_section": "使用習慣",
@@ -539,7 +539,9 @@
     "quota_aware_action_failed": "無法切換額度感知模式。",
     "claude_beginner_error": "新手模式：{error}",
     "claude_desktop_updated": "Claude 桌面版 · {minutes} 分鐘前更新",
-    "claude_desktop_stale": "Claude 桌面版 · 資料過期 · {minutes} 分鐘前更新"
+    "claude_desktop_stale": "Claude 桌面版 · 資料過期 · {minutes} 分鐘前更新",
+    "report_project_others": "其他專案",
+    "report_ledger_pct_note": "Claude、Codex、Antigravity 三欄是約佔該工具週額度的百分比。"
   },
   "en": {
     "panel_default_name": "Default",
@@ -802,8 +804,8 @@
     "report_fixed_range": "Fixed range",
     "report_fixed_group_note": "The sections below don't follow the date filter above",
     "report_model": "Model",
-    "report_appendix_title": "How these numbers are calculated",
-    "report_appendix_desc": "Token mix · Cache hit rate · Cost confidence",
+    "report_appendix_title": "How cost is calculated",
+    "report_appendix_desc": "Public API price conversion · Cost confidence",
     "report_narrative": "You burned {tokens} tokens. Peak was {peak_date} ({peak_tokens}/day). Top model: {top_model}.",
     "report_period": "Period",
     "report_project": "Project",
@@ -812,7 +814,7 @@
     "report_persona_active_hours": "Active hours",
     "report_persona_caption": "You most often collaborate with AI at {h1}{h2}",
     "report_persona_caption_second": " and {h2}",
-    "report_persona_peak": "Peak {count} messages",
+    "report_persona_peak": "Peak: {count} messages (incl. tool calls)",
     "report_persona_empty": "Not enough data in this period yet",
     "report_recent_titles_heading": "What you worked on",
     "report_persona_section": "Usage habits",
@@ -1081,7 +1083,9 @@
     "quota_aware_action_failed": "Could not change Quota-Aware Mode.",
     "claude_beginner_error": "Beginner Mode: {error}",
     "claude_desktop_updated": "Claude Desktop · updated {minutes}m ago",
-    "claude_desktop_stale": "Claude Desktop · stale · updated {minutes}m ago"
+    "claude_desktop_stale": "Claude Desktop · stale · updated {minutes}m ago",
+    "report_project_others": "Other projects",
+    "report_ledger_pct_note": "The Claude, Codex, and Antigravity columns are approximate shares of each tool’s weekly quota."
   },
   "zh-CN": {
     "panel_default_name": "默认",
@@ -1344,8 +1348,8 @@
     "report_fixed_range": "Fixed range",
     "report_fixed_group_note": "以下区块不受上方日期筛选影响",
     "report_model": "模型",
-    "report_appendix_title": "数字怎么算的",
-    "report_appendix_desc": "Token 组成 · 缓存命中率 · 花费可信度",
+    "report_appendix_title": "花费怎么算的",
+    "report_appendix_desc": "公开 API 价格换算 · 花费可信度",
     "report_narrative": "过去这段时间你烧了 {tokens} tokens。{peak_date} 是高峰（{peak_tokens}/天），主力 LLM 是 {top_model}。",
     "report_period": "区间",
     "report_project": "项目",
@@ -1354,7 +1358,7 @@
     "report_persona_active_hours": "活跃时段",
     "report_persona_caption": "你最常在 {h1}{h2} 与 AI 协作",
     "report_persona_caption_second": " 和 {h2}",
-    "report_persona_peak": "峰值 {count} 条",
+    "report_persona_peak": "峰值 {count} 条消息（含工具调用）",
     "report_persona_empty": "这段期间还没有足够数据",
     "report_recent_titles_heading": "最近在做什么",
     "report_persona_section": "使用习惯",
@@ -1623,7 +1627,9 @@
     "quota_aware_action_failed": "无法切换额度感知模式。",
     "claude_beginner_error": "新手模式：{error}",
     "claude_desktop_updated": "Claude 桌面版 · {minutes} 分钟前更新",
-    "claude_desktop_stale": "Claude 桌面版 · 数据过期 · {minutes} 分钟前更新"
+    "claude_desktop_stale": "Claude 桌面版 · 数据过期 · {minutes} 分钟前更新",
+    "report_project_others": "其他项目",
+    "report_ledger_pct_note": "Claude、Codex、Antigravity 三列是约占该工具周额度的百分比。"
   },
   "ja": {
     "panel_default_name": "デフォルト",
@@ -1886,8 +1892,8 @@
     "report_fixed_range": "Fixed range",
     "report_fixed_group_note": "以下のセクションは上の日付フィルターの影響を受けません",
     "report_model": "モデル",
-    "report_appendix_title": "数値の算出方法",
-    "report_appendix_desc": "トークン構成 · キャッシュヒット率 · コストの信頼度",
+    "report_appendix_title": "コストの算出方法",
+    "report_appendix_desc": "公開 API 料金での換算 · コストの信頼度",
     "report_narrative": "この期間に {tokens} tokens を使いました。ピークは {peak_date}（{peak_tokens}/日）。主力モデル：{top_model}。",
     "report_period": "期間",
     "report_project": "プロジェクト",
@@ -1896,7 +1902,7 @@
     "report_persona_active_hours": "アクティブな時間帯",
     "report_persona_caption": "{h1}{h2} の時間帯に AI との共同作業が最も多い傾向があります",
     "report_persona_caption_second": " と {h2}",
-    "report_persona_peak": "ピーク {count} 件",
+    "report_persona_peak": "ピーク: {count} 件のメッセージ（ツール呼び出しを含む）",
     "report_persona_empty": "この期間はまだ十分なデータがありません",
     "report_recent_titles_heading": "最近の作業",
     "report_persona_section": "利用習慣",
@@ -2165,7 +2171,9 @@
     "quota_aware_action_failed": "クォータ認識モードを切り替えられませんでした。",
     "claude_beginner_error": "初心者モード：{error}",
     "claude_desktop_updated": "Claude デスクトップ · {minutes}分前に更新",
-    "claude_desktop_stale": "Claude デスクトップ · 古いデータ · {minutes}分前に更新"
+    "claude_desktop_stale": "Claude デスクトップ · 古いデータ · {minutes}分前に更新",
+    "report_project_others": "その他のプロジェクト",
+    "report_ledger_pct_note": "Claude、Codex、Antigravity の各列は、各ツールの週間上限に対する推定使用率です。"
   },
   "ko": {
     "panel_default_name": "기본",
@@ -2428,8 +2436,8 @@
     "report_fixed_range": "Fixed range",
     "report_fixed_group_note": "아래 섹션은 위의 날짜 필터와 관계없이 표시됩니다",
     "report_model": "모델",
-    "report_appendix_title": "수치 계산 방식",
-    "report_appendix_desc": "토큰 구성 · 캐시 적중률 · 비용 신뢰도",
+    "report_appendix_title": "비용 계산 방식",
+    "report_appendix_desc": "공개 API 가격 환산 · 비용 신뢰도",
     "report_narrative": "이 기간 동안 {tokens} tokens을 사용했습니다. 최고점은 {peak_date}({peak_tokens}/일). 주력 모델: {top_model}.",
     "report_period": "기간",
     "report_project": "프로젝트",
@@ -2438,7 +2446,7 @@
     "report_persona_active_hours": "활동 시간대",
     "report_persona_caption": "주로 {h1}{h2}에 AI와 협업합니다",
     "report_persona_caption_second": " 및 {h2}",
-    "report_persona_peak": "최고 {count}건",
+    "report_persona_peak": "최고 {count}개 메시지(도구 호출 포함)",
     "report_persona_empty": "이 기간에는 아직 충분한 데이터가 없습니다",
     "report_recent_titles_heading": "최근 작업",
     "report_persona_section": "사용 습관",
@@ -2707,6 +2715,8 @@
     "quota_aware_action_failed": "할당량 인식 모드를 변경할 수 없습니다.",
     "claude_beginner_error": "초보자 모드: {error}",
     "claude_desktop_updated": "Claude 데스크톱 · {minutes}분 전 업데이트",
-    "claude_desktop_stale": "Claude 데스크톱 · 오래된 데이터 · {minutes}분 전 업데이트"
+    "claude_desktop_stale": "Claude 데스크톱 · 오래된 데이터 · {minutes}분 전 업데이트",
+    "report_project_others": "기타 프로젝트",
+    "report_ledger_pct_note": "Claude, Codex, Antigravity 열은 각 도구의 주간 한도 대비 대략적인 사용 비율입니다."
   }
 }

{usage_cli-0.33.5 → usage_cli-0.33.7}/loaders/agy_quota_probe.py

@@ -76,6 +76,9 @@ _CLIENT_SECRET = "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"
 _DEFAULT_RETRY_AFTER_SECONDS = 60.0
 _MAX_RETRY_AFTER_SECONDS = 3600.0
 _rate_limit_until_monotonic = 0.0
+# When each group last appeared in a real API response; in memory only, reset on restart.
+_group_seen_at: dict[str, datetime] = {}
+_MISSING_GROUP_GRACE_MINUTES = 30
 
 
 def _user_agent() -> str:
@@ -160,10 +163,38 @@ def load_quota(max_age_minutes: float = 5) -> AgyQuotaResult | None:
     probed = probe_quota()
     if probed is None:
         return cached
+    probed = _carry_missing_groups(probed, cached)
     _write_cache(probed)
     return probed
 
 
+def _carry_missing_groups(probed: AgyQuotaResult, cached: AgyQuotaResult | None) -> AgyQuotaResult:
+    """Keep a group the API skipped this once, so the group toggle has something to show.
+
+    A group is carried only while the API last returned it within the grace window, so a
+    group Google really removes drops out instead of living on in the cache forever.
+    """
+    now = datetime.now(UTC)
+    for group in probed.groups:
+        _group_seen_at[group.name] = now
+    if cached is None:
+        return probed
+    names = {group.name for group in probed.groups}
+    grace = timedelta(minutes=_MISSING_GROUP_GRACE_MINUTES)
+    missing = [
+        group
+        for group in cached.groups
+        if group.name not in names
+        and group.name in _group_seen_at
+        and now - _group_seen_at[group.name] <= grace
+    ]
+    if not missing:
+        return probed
+    order = {group.name: index for index, group in enumerate(cached.groups)}
+    groups = sorted([*probed.groups, *missing], key=lambda group: order.get(group.name, 0))
+    return AgyQuotaResult(groups=groups, fetched_at=probed.fetched_at)
+
+
 def _resolve_access_token(timeout: float) -> str | None:
     """Return a usable access token, refreshing when stale.