usage-cli 0.33.0__tar.gz → 0.33.1__tar.gz

{usage_cli-0.33.0 → usage_cli-0.33.1}/PKG-INFO

@@ -1,12 +1,13 @@
 Metadata-Version: 2.4
 Name: usage-cli
-Version: 0.33.0
+Version: 0.33.1
 Summary: usage — 在 macOS menu bar 與 Windows 系統匣顯示 Claude Code、Codex、Antigravity 用量的小工具（也提供終端機 TUI）
 License-Expression: AGPL-3.0-only
 Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: zstandard<1.0.0,>=0.25.0
 Requires-Dist: pyobjc-framework-Cocoa>=11.0; sys_platform == "darwin"
 Requires-Dist: pyobjc-framework-Quartz>=11.0; sys_platform == "darwin"
 Requires-Dist: pyobjc-framework-UserNotifications>=11.0; sys_platform == "darwin"
@@ -101,6 +102,8 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 ## Privacy & Data Sources
 
+Claude Desktop chat quota is also supported without installing the standalone Claude Code CLI or configuring a status line. Keep Claude Desktop open: when Claude Code quota files are unavailable, usage reads its local `plan-usage-history.json` (including Microsoft Store installations on Windows). When a recent response in its local Chromium block-file HTTP cache matches the organization, usage also reads the exact session and weekly reset times. Newer cached observations take precedence over throttled history samples; older cache must match the percentages. Missing, unsupported, expired, or inconsistent cache data leaves the countdown unknown; times are never estimated. Desktop samples normally update every 5–15 minutes. The panel shows the observation age, marks it stale after 30 minutes, and stops displaying it after two hours. The most recent organization sample is used; custom desktop profiles are not discovered. No cookies, login tokens, or API calls are needed. These quota caches contain no per-project token counts. Desktop sessions that also write compatible Claude Code logs under `~/.claude/projects/` are counted by the existing project/token reports.
+
 - Claude Code and Codex numbers are read from local log files on your machine.
 - Antigravity quota requires network access, and only if you use it: quota is fetched from Google's official quota endpoint using 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` reads that credential without writing it back and keeps any refreshed access token in memory only; the call itself reads quota metadata.
 - Background network activity: the Antigravity quota/token endpoints above, public Claude and Codex status pages to flag outages, a public model-pricing table to estimate cost (falls back to built-in prices offline), and occasionally checking GitHub for a new version. Claude Code and Codex log contents are never uploaded.
@@ -109,7 +112,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 ## Requirements
 
 - macOS 12 (Monterey) or newer, or Windows 10/11
-- Claude Code, Codex, Antigravity, or Grok CLI has been used at least once (so local usage data exists).
+- Local usage data from Claude Code, Codex, Antigravity, or Grok CLI, or a running Claude Desktop app with plan-usage history.
 - (Source runs only) Python 3.13.
 
 ## Install

{usage_cli-0.33.0 → usage_cli-0.33.1}/README.md

@@ -80,6 +80,8 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 
 ## Privacy & Data Sources
 
+Claude Desktop chat quota is also supported without installing the standalone Claude Code CLI or configuring a status line. Keep Claude Desktop open: when Claude Code quota files are unavailable, usage reads its local `plan-usage-history.json` (including Microsoft Store installations on Windows). When a recent response in its local Chromium block-file HTTP cache matches the organization, usage also reads the exact session and weekly reset times. Newer cached observations take precedence over throttled history samples; older cache must match the percentages. Missing, unsupported, expired, or inconsistent cache data leaves the countdown unknown; times are never estimated. Desktop samples normally update every 5–15 minutes. The panel shows the observation age, marks it stale after 30 minutes, and stops displaying it after two hours. The most recent organization sample is used; custom desktop profiles are not discovered. No cookies, login tokens, or API calls are needed. These quota caches contain no per-project token counts. Desktop sessions that also write compatible Claude Code logs under `~/.claude/projects/` are counted by the existing project/token reports.
+
 - Claude Code and Codex numbers are read from local log files on your machine.
 - Antigravity quota requires network access, and only if you use it: quota is fetched from Google's official quota endpoint using 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` reads that credential without writing it back and keeps any refreshed access token in memory only; the call itself reads quota metadata.
 - Background network activity: the Antigravity quota/token endpoints above, public Claude and Codex status pages to flag outages, a public model-pricing table to estimate cost (falls back to built-in prices offline), and occasionally checking GitHub for a new version. Claude Code and Codex log contents are never uploaded.
@@ -88,7 +90,7 @@ It lands in your Applications folder automatically. Open it once; if macOS 15 or
 ## Requirements
 
 - macOS 12 (Monterey) or newer, or Windows 10/11
-- Claude Code, Codex, Antigravity, or Grok CLI has been used at least once (so local usage data exists).
+- Local usage data from Claude Code, Codex, Antigravity, or Grok CLI, or a running Claude Desktop app with plan-usage history.
 - (Source runs only) Python 3.13.
 
 ## Install

usage_cli-0.33.1/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,96 @@
+# Third-party notices
+
+The Windows taskbar label anchoring in `wintray/taskbar_overlay.py` is adapted
+from [Codex Usage Widget](https://github.com/ognjeeen/codex-usage-widget),
+commit `940d722d4044242bbe73f8056014449c2ef827a7`, particularly
+`Infrastructure/Windows/TaskbarWindowInterop.cs`.
+
+MIT License
+
+Copyright (c) 2026 Ognjen Marinković
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+## Python Zstandard
+
+The local Claude HTTP cache reader uses python-zstandard, including its bundled
+Zstandard library, under their BSD licenses.
+
+Copyright (c) 2016, Gregory Szorc
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+## Zstandard
+
+BSD License
+
+For Zstandard software
+
+Copyright (c) Meta Platforms, Inc. and affiliates. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+ * Neither the name Facebook, nor Meta, nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

{usage_cli-0.33.0 → usage_cli-0.33.1}/adapters/rate_limits.py

@@ -10,6 +10,8 @@ import os
 from datetime import datetime, timezone
 from typing import Any
 
+import usage_client
+
 from .types import RateLimits
 
 STATUS_FILE = os.path.expanduser("~/.claude/usage-status.json")
@@ -42,8 +44,12 @@ def _read_status() -> dict[str, Any] | None:
 
 def load_rate_limits() -> RateLimits | None:
     data = _read_status()
-    if data is None:
-        return None
+    if data is None or not usage_client._has_complete_rate_limits(data):
+        snapshot = usage_client.read_quota_fallback()
+        if snapshot is not None:
+            return _snapshot_rate_limits(snapshot)
+        if data is None:
+            return None
 
     rl = data.get("rate_limits") or {}
     five = rl.get("five_hour") or {}
@@ -74,3 +80,18 @@ def load_rate_limits() -> RateLimits | None:
         model=model_name,
         updated_at=data.get("_received_at", ""),
     )
+
+
+def _snapshot_rate_limits(quota: usage_client.UsageSnapshot) -> RateLimits:
+    return RateLimits(
+        five_hour_pct=quota.current_percent,
+        seven_day_pct=quota.weekly_percent,
+        five_hour_resets_at=int(quota.current_reset_at)
+        if quota.current_reset_at is not None
+        else None,
+        seven_day_resets_at=int(quota.weekly_reset_at)
+        if quota.weekly_reset_at is not None
+        else None,
+        model="",
+        updated_at=datetime.fromtimestamp(quota.polled_at, timezone.utc).isoformat(),
+    )

{usage_cli-0.33.0 → usage_cli-0.33.1}/i18n.json

@@ -69,7 +69,7 @@
     "awaiting_rate_limits": "請對 Claude Code 發送一句訊息以同步配額",
     "hook_broken_not_installed": "⚠ 狀態列沒在更新，請按「設定狀態列」重新安裝",
     "hook_broken_restart": "⚠ 狀態列沒在運作，請重開一次 Claude Code",
-    "usage_status_missing": "⚠ 找不到狀態檔，請按「設定狀態列」，再打開一次 Claude Code",
+    "usage_status_missing": "尚無額度資料。請保持 Claude 桌面版開啟，或設定狀態列後啟動終端機的 Claude Code。",
     "usage_status_missing_active": "⚠ 配額資料只能靠終端機的狀態列同步，桌面版／背景工作階段不會觸發，請開一次終端機的 Claude Code 來同步",
     "usage_status_no_quota": "⚠ 狀態檔尚無配額資料，等 Claude Code 再刷新一次 statusLine",
     "status_error": "錯誤 ({message})",
@@ -542,7 +542,9 @@
     "quota_aware_enabled_msg": "已開啟額度感知模式。請重啟 Claude Code 套用。",
     "quota_aware_disabled_msg": "已關閉額度感知模式。請重啟 Claude Code 套用。",
     "quota_aware_action_failed": "無法切換額度感知模式。",
-    "claude_beginner_error": "新手模式：{error}"
+    "claude_beginner_error": "新手模式：{error}",
+    "claude_desktop_updated": "Claude 桌面版 · {minutes} 分鐘前更新",
+    "claude_desktop_stale": "Claude 桌面版 · 資料過期 · {minutes} 分鐘前更新"
   },
   "en": {
     "panel_default_name": "Default",
@@ -614,7 +616,7 @@
     "awaiting_rate_limits": "Send a message in Claude Code to sync your quota",
     "hook_broken_not_installed": "⚠ Status line is not updating. Click \"Set Up Status Line\" to reinstall it.",
     "hook_broken_restart": "⚠ Status line hook is not running. Restart Claude Code once.",
-    "usage_status_missing": "⚠ Status file not found. Click \"Set Up Status Line\", then open Claude Code once.",
+    "usage_status_missing": "No quota data yet. Keep Claude Desktop open, or set up the status line and start Claude Code in a terminal.",
     "usage_status_missing_active": "⚠ Quota data only syncs via the terminal status line — the desktop app and headless sessions don't trigger it. Open Claude Code in a terminal once to sync.",
     "usage_status_no_quota": "⚠ Status file has no quota data yet. Wait for Claude Code to refresh statusLine once.",
     "status_error": "Error ({message})",
@@ -1087,7 +1089,9 @@
     "quota_aware_enabled_msg": "Quota-Aware Mode enabled. Restart Claude Code to apply.",
     "quota_aware_disabled_msg": "Quota-Aware Mode disabled. Restart Claude Code to apply.",
     "quota_aware_action_failed": "Could not change Quota-Aware Mode.",
-    "claude_beginner_error": "Beginner Mode: {error}"
+    "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"
   },
   "zh-CN": {
     "panel_default_name": "默认",
@@ -1159,7 +1163,7 @@
     "awaiting_rate_limits": "请对 Claude Code 发送一句消息以同步配额",
     "hook_broken_not_installed": "⚠ 状态栏没有更新，请点「设置状态栏」重新安装",
     "hook_broken_restart": "⚠ 状态栏没有运行，请重开一次 Claude Code",
-    "usage_status_missing": "⚠ 找不到状态文件，请点「设置状态栏」，再打开一次 Claude Code",
+    "usage_status_missing": "尚无额度数据。请保持 Claude 桌面版打开，或设置状态栏后启动终端中的 Claude Code。",
     "usage_status_missing_active": "⚠ 配额数据只能靠终端的状态栏同步，桌面版／后台会话不会触发，请打开一次终端的 Claude Code 来同步",
     "usage_status_no_quota": "⚠ 状态文件还没有配额数据，等 Claude Code 再刷新一次 statusLine",
     "status_error": "错误 ({message})",
@@ -1632,7 +1636,9 @@
     "quota_aware_enabled_msg": "已开启额度感知模式。请重启 Claude Code 应用。",
     "quota_aware_disabled_msg": "已关闭额度感知模式。请重启 Claude Code 应用。",
     "quota_aware_action_failed": "无法切换额度感知模式。",
-    "claude_beginner_error": "新手模式：{error}"
+    "claude_beginner_error": "新手模式：{error}",
+    "claude_desktop_updated": "Claude 桌面版 · {minutes} 分钟前更新",
+    "claude_desktop_stale": "Claude 桌面版 · 数据过期 · {minutes} 分钟前更新"
   },
   "ja": {
     "panel_default_name": "デフォルト",
@@ -1704,7 +1710,7 @@
     "awaiting_rate_limits": "Claude Code にメッセージを送信してクォータを同期してください",
     "hook_broken_not_installed": "⚠ ステータスラインが更新されていません。「ステータスラインを設定」を押して再インストールしてください。",
     "hook_broken_restart": "⚠ ステータスライン hook が動作していません。Claude Code を一度再起動してください。",
-    "usage_status_missing": "⚠ ステータスファイルが見つかりません。「ステータスラインを設定」を押してから、Claude Code を一度起動してください。",
+    "usage_status_missing": "利用枠データがありません。Claude デスクトップを開いたままにするか、ステータスラインを設定してターミナルの Claude Code を起動してください。",
     "usage_status_missing_active": "⚠ クォータ情報はターミナルのステータスラインでのみ同期されます。デスクトップアプリやヘッドレスセッションでは同期されません。ターミナルで Claude Code を一度開いてください。",
     "usage_status_no_quota": "⚠ ステータスファイルにクォータデータがまだありません。Claude Code が statusLine をもう一度更新するまでお待ちください。",
     "status_error": "エラー ({message})",
@@ -2177,7 +2183,9 @@
     "quota_aware_enabled_msg": "クォータ認識モードを有効にしました。Claude Code を再起動してください。",
     "quota_aware_disabled_msg": "クォータ認識モードを無効にしました。Claude Code を再起動してください。",
     "quota_aware_action_failed": "クォータ認識モードを切り替えられませんでした。",
-    "claude_beginner_error": "初心者モード：{error}"
+    "claude_beginner_error": "初心者モード：{error}",
+    "claude_desktop_updated": "Claude デスクトップ · {minutes}分前に更新",
+    "claude_desktop_stale": "Claude デスクトップ · 古いデータ · {minutes}分前に更新"
   },
   "ko": {
     "panel_default_name": "기본",
@@ -2249,7 +2257,7 @@
     "awaiting_rate_limits": "Claude Code에 메시지를 보내 할당량을 동기화하세요",
     "hook_broken_not_installed": "⚠ 상태 표시줄이 업데이트되지 않습니다. \"상태 표시줄 설정\"을 눌러 다시 설치하세요.",
     "hook_broken_restart": "⚠ 상태 표시줄 hook이 작동하지 않습니다. Claude Code를 한 번 다시 시작하세요.",
-    "usage_status_missing": "⚠ 상태 파일을 찾을 수 없습니다. \"상태 표시줄 설정\"을 누른 뒤 Claude Code를 한 번 여세요.",
+    "usage_status_missing": "사용 한도 데이터가 없습니다. Claude 데스크톱을 열어 두거나 상태 표시줄을 설정한 뒤 터미널에서 Claude Code를 실행하세요.",
     "usage_status_missing_active": "⚠ 할당량 데이터는 터미널 상태 표시줄로만 동기화됩니다. 데스크톱 앱이나 헤드리스 세션에서는 동기화되지 않습니다. 터미널에서 Claude Code를 한 번 열어주세요.",
     "usage_status_no_quota": "⚠ 상태 파일에 아직 할당량 데이터가 없습니다. Claude Code가 statusLine을 한 번 더 새로 고칠 때까지 기다리세요.",
     "status_error": "오류 ({message})",
@@ -2722,6 +2730,8 @@
     "quota_aware_enabled_msg": "할당량 인식 모드를 켰습니다. Claude Code를 다시 시작해 주세요.",
     "quota_aware_disabled_msg": "할당량 인식 모드를 껐습니다. Claude Code를 다시 시작해 주세요.",
     "quota_aware_action_failed": "할당량 인식 모드를 변경할 수 없습니다.",
-    "claude_beginner_error": "초보자 모드: {error}"
+    "claude_beginner_error": "초보자 모드: {error}",
+    "claude_desktop_updated": "Claude 데스크톱 · {minutes}분 전 업데이트",
+    "claude_desktop_stale": "Claude 데스크톱 · 오래된 데이터 · {minutes}분 전 업데이트"
   }
 }

usage_cli-0.33.1/loaders/_shared_cache_file.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""Read a cache file while Chromium holds it open, without changing the file."""
+
+from __future__ import annotations
+
+import ctypes as C
+import sys
+from ctypes import wintypes as W
+from functools import lru_cache
+from pathlib import Path
+
+
+@lru_cache(maxsize=1)
+def _kernel() -> C.CDLL:
+    if sys.platform != "win32":
+        raise OSError("Windows shared cache reader is unavailable")
+    kernel = C.WinDLL("kernel32", use_last_error=True)
+    kernel.CreateFileW.argtypes = [
+        W.LPCWSTR,
+        W.DWORD,
+        W.DWORD,
+        C.c_void_p,
+        W.DWORD,
+        W.DWORD,
+        C.c_void_p,
+    ]
+    kernel.CreateFileW.restype = W.HANDLE
+    kernel.SetFilePointerEx.argtypes = [W.HANDLE, C.c_longlong, C.c_void_p, W.DWORD]
+    kernel.SetFilePointerEx.restype = W.BOOL
+    kernel.ReadFile.argtypes = [W.HANDLE, C.c_void_p, W.DWORD, C.POINTER(W.DWORD), C.c_void_p]
+    kernel.ReadFile.restype = W.BOOL
+    kernel.CloseHandle.argtypes = [W.HANDLE]
+    kernel.CloseHandle.restype = W.BOOL
+    return kernel
+
+
+def read_range(path: Path, offset: int, length: int) -> bytes:
+    if offset < 0 or length < 0 or length > 16 * 1024 * 1024:
+        raise ValueError("Invalid cache read bounds")
+    if sys.platform != "win32":
+        with path.open("rb") as file:
+            file.seek(offset)
+            return file.read(length)
+    kernel = _kernel()
+    # GENERIC_READ, FILE_SHARE_READ | WRITE | DELETE, OPEN_EXISTING. Chromium
+    # requests delete access; ordinary CRT opens do not always share that access.
+    handle = kernel.CreateFileW(str(path), 0x80000000, 7, None, 3, 0, None)
+    if handle == C.c_void_p(-1).value:
+        raise OSError("Cannot open the cache file for reading")
+    try:
+        if not kernel.SetFilePointerEx(handle, offset, None, 0):
+            raise OSError("Cannot seek in the cache file")
+        buffer = C.create_string_buffer(length)
+        count = W.DWORD()
+        if not kernel.ReadFile(handle, buffer, length, C.byref(count), None):
+            raise OSError("Cannot read the cache file")
+        return buffer.raw[: count.value]
+    finally:
+        kernel.CloseHandle(handle)
+
+
+def read_bounded(path: Path, limit: int) -> bytes:
+    size = path.stat().st_size
+    if size > limit:
+        raise ValueError("Cache file exceeds the size limit")
+    return read_range(path, 0, size)

usage_cli-0.33.1/loaders/chromium_cache.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+
+"""Read one local JSON response from Chromium's block-file HTTP cache.
+
+Formats: Chromium net/disk_cache/blockfile/{disk_format,addr}.h and
+net/http/http_response_info.cc. No cookies, credentials, or requests are used.
+Unsupported formats and incomplete/in-flight entries return no response.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import struct
+import zlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from loaders._shared_cache_file import read_bounded, read_range
+
+MAX_BODY = 1024 * 1024
+MAX_WINDOW = 8 * 1024 * 1024
+MAX_INDEX = 4 * 1024 * 1024
+MAX_ENTRIES = 16 * 1024 * 1024
+BLOCK_SIZES = {1: 36, 2: 256, 3: 1024, 4: 4096, 5: 8, 6: 256, 7: 256}
+INDEX_HEADER = 368
+BLOCK_HEADER = 8192
+TIME_EPOCH = 11644473600
+
+
+@dataclass(frozen=True)
+class CachedResponse:
+    data: dict[str, object]
+    fetched_at: float
+
+
+def _response_info(raw: bytes) -> tuple[float, bytes]:
+    if len(raw) < 28 or struct.unpack_from("<I", raw)[0] != len(raw) - 4:
+        raise ValueError("Invalid response info")
+    flags = struct.unpack_from("<I", raw, 4)[0]
+    if flags & 255 != 3 or flags & (1 << 12):
+        raise ValueError("Unsupported or truncated response")
+    extra = struct.unpack_from("<I", raw, 8)[0] if flags & (1 << 31) else 0
+    offset = 12 if flags & (1 << 31) else 8
+    fetched_at = struct.unpack_from("<q", raw, offset + 8)[0] / 1e6 - TIME_EPOCH
+    offset += 16 + (8 if extra & 4 else 0)
+    length = struct.unpack_from("<I", raw, offset)[0]
+    headers = raw[offset + 4 : offset + 4 + length]
+    if len(headers) != length or not re.match(rb"^HTTP/\S+ 200(?: |\x00)", headers):
+        raise ValueError("No successful response headers")
+    if b"application/json" not in headers.lower():
+        raise ValueError("Not a JSON response")
+    return fetched_at, headers
+
+
+def _decode(raw: bytes, headers: bytes) -> dict[str, object]:
+    # Chrome may store a zstd frame even when the original HTTP response used
+    # another encoding. Detect the on-disk frame first.
+    if raw.startswith(b"\x28\xb5\x2f\xfd"):
+        try:
+            import zstandard
+        except (ImportError, OSError) as exc:
+            raise ValueError("Zstandard decoder is unavailable") from exc
+        try:
+            size = zstandard.frame_content_size(raw)
+            if size != zstandard.CONTENTSIZE_UNKNOWN and size > MAX_BODY:
+                raise ValueError("Response body exceeds the size limit")
+            if zstandard.get_frame_parameters(raw).window_size > MAX_WINDOW:
+                raise ValueError("Response compression window exceeds the size limit")
+            decoder = zstandard.ZstdDecompressor(max_window_size=MAX_WINDOW)
+            raw = decoder.decompress(raw, max_output_size=MAX_BODY, allow_extra_data=False)
+        except zstandard.ZstdError as exc:
+            raise ValueError("Invalid Zstandard response") from exc
+    elif raw.startswith(b"\x1f\x8b") or b"content-encoding: deflate" in headers.lower():
+        decoder_z = zlib.decompressobj(31 if raw.startswith(b"\x1f\x8b") else 15)
+        raw = decoder_z.decompress(raw, MAX_BODY + 1)
+        if not decoder_z.eof:
+            raise ValueError("Incomplete or oversized compressed response")
+    if len(raw) > MAX_BODY:
+        raise ValueError("Response body exceeds the size limit")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("Not a JSON object")
+    return cast(dict[str, object], data)
+
+
+class _BlockCache:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.index = read_bounded(path / "index", MAX_INDEX)
+        magic, version = struct.unpack_from("<II", self.index)
+        if magic != 0xC103CAC3 or version not in {0x20000, 0x20001, 0x30000}:
+            raise ValueError("Unsupported cache index")
+        self.table_len = struct.unpack_from("<i", self.index, 28)[0] or 65536
+        if (
+            self.table_len <= 0
+            or self.table_len & (self.table_len - 1)
+            or len(self.index) != INDEX_HEADER + 4 * self.table_len
+        ):
+            raise ValueError("Invalid cache index size")
+
+    def stream(self, address: int, length: int) -> bytes:
+        if not address & 0x80000000 or not 0 < length <= MAX_BODY:
+            raise ValueError("Invalid cache stream")
+        kind = (address >> 28) & 7
+        if kind == 0:
+            raw = read_range(self.path / f"f_{address & 0x0FFFFFFF:06x}", 0, length)
+        else:
+            size = BLOCK_SIZES[kind]
+            if length > size * (((address >> 24) & 3) + 1):
+                raise ValueError("Invalid block allocation")
+            offset = BLOCK_HEADER + (address & 65535) * size
+            raw = read_range(self.path / f"data_{(address >> 16) & 255}", offset, length)
+        if len(raw) != length:
+            raise ValueError("Incomplete cache stream")
+        return raw
+
+    def _active(self, entry: bytes, file: int, block: int) -> bool:
+        bucket = struct.unpack_from("<I", entry)[0] & (self.table_len - 1)
+        address = struct.unpack_from("<I", self.index, INDEX_HEADER + bucket * 4)[0]
+        visited: set[int] = set()
+        for _ in range(128):
+            if not address or address in visited or (address >> 28) & 7 not in {2, 6}:
+                return False
+            visited.add(address)
+            if ((address >> 16) & 255, address & 65535) == (file, block):
+                return True
+            address = struct.unpack_from("<I", self.stream(address, 256), 4)[0]
+        return False
+
+    def responses(self, url: bytes, earliest: float, now: float) -> list[CachedResponse]:
+        files = {
+            (address >> 16) & 255
+            for (address,) in struct.iter_unpack("<I", self.index[INDEX_HEADER:])
+            if (address >> 28) & 7 in {2, 6}
+        }
+        results = []
+        for file in sorted(files):
+            try:
+                raw = read_bounded(self.path / f"data_{file}", MAX_ENTRIES)
+            except (OSError, ValueError):
+                continue
+            if (
+                len(raw) < BLOCK_HEADER
+                or struct.unpack_from("<II", raw) != (0xC104CAC3, 0x20000)
+                or struct.unpack_from("<H", raw, 8)[0] != file
+                or struct.unpack_from("<i", raw, 12)[0] != 256
+            ):
+                continue
+            for offset in range(BLOCK_HEADER, len(raw) - 255, 256):
+                entry = raw[offset : offset + 256]
+                try:
+                    response = self._response(raw, offset, entry, file, url, earliest, now)
+                except (
+                    OSError,
+                    ValueError,
+                    struct.error,
+                    zlib.error,
+                    RecursionError,
+                ):
+                    continue
+                if response is not None:
+                    results.append(response)
+        return results
+
+    def _response(
+        self,
+        raw: bytes,
+        offset: int,
+        entry: bytes,
+        file: int,
+        url: bytes,
+        earliest: float,
+        now: float,
+    ) -> CachedResponse | None:
+        if struct.unpack_from("<i", entry, 20)[0] != 0:
+            return None
+        key_len, long_key = struct.unpack_from("<iI", entry, 32)
+        if not 0 < key_len <= 4096:
+            return None
+        key = (
+            self.stream(long_key, key_len) if long_key else raw[offset + 96 : offset + 96 + key_len]
+        )
+        # Chromium prefixes keys with upload identifiers (e.g. "1/0/") and
+        # may also add a network-isolation key before the request URL.
+        if key[key.rfind(b"https://") :].partition(b"?")[0] != url:
+            return None
+        if not self._active(entry, file, (offset - BLOCK_HEADER) // 256):
+            return None
+        ranking = self.stream(struct.unpack_from("<I", entry, 8)[0], 36)
+        if struct.unpack_from("<i", ranking, 28)[0] != 0:
+            return None
+        sizes = struct.unpack_from("<4i", entry, 40)
+        addresses = struct.unpack_from("<4I", entry, 56)
+        metadata = self.stream(addresses[0], sizes[0])
+        fetched_at, headers = _response_info(metadata)
+        if not max(earliest, now - 7200) <= fetched_at <= now + 60:
+            return None
+        body = self.stream(addresses[1], sizes[1])
+        # Cache updates are concurrent; refuse entries whose metadata changed
+        # while reading. No files are copied, modified, or locked exclusively.
+        if read_range(self.path / f"data_{file}", offset, 96) != entry[:96]:
+            return None
+        if self.stream(addresses[0], sizes[0]) != metadata:
+            return None
+        return CachedResponse(_decode(body, headers), fetched_at)
+
+
+def load_cached_json(path: Path, url: bytes, earliest: float, now: float) -> CachedResponse | None:
+    try:
+        responses = _BlockCache(path).responses(url, earliest, now)
+    except (OSError, ValueError, struct.error):
+        return None
+    return max(responses, key=lambda response: response.fetched_at, default=None)