pythinker-code 0.37.0__tar.gz → 0.38.0__tar.gz

{pythinker_code-0.37.0 → pythinker_code-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pythinker-code
-Version: 0.37.0
+Version: 0.38.0
 Summary: Pythinker — an agentic CLI developed by Pythoughts-labs.
 Keywords: cli,agent,ai,coding-assistant,llm,claude,openai,terminal
 Author: Pythoughts-labs
@@ -30,8 +30,8 @@ Requires-Dist: pillow==12.2.0
 Requires-Dist: pyyaml==6.0.3
 Requires-Dist: rich==15.0.0
 Requires-Dist: certifi>=2025.10.5
-Requires-Dist: click==8.3.0
 Requires-Dist: pyperclip==1.11.0
+Requires-Dist: click==8.3.0
 Requires-Dist: streamingjson==0.0.5
 Requires-Dist: trafilatura==2.0.0
 Requires-Dist: lxml==6.1.1
@@ -115,16 +115,14 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 0.37.0
+## 🆕 What's New in 0.38.0
 
-- **Agent runtime tool visibility hardening.** `PythinkerToolset` now gates tool advertisements by execution policy, permission profile, root/subagent role, and plan-mode state — execution-time guards remain as defense in depth.
-- **Agent design upgrades.** New `ask` and `debug` primary agents selectable with `--agent`, a `scout` subagent for docs/API freshness research, richer spec metadata, and stable compaction summaries.
-- **Prompt-injection defense: `UntrustedData` wrapper.** External file and web content is wrapped in signed `<untrusted_data>` tags before reaching the LLM, with breakout-prevention escaping.
-- **Agent boundary artifacts.** Typed `CodingArtifact`/`VerificationResult` and `VulnerabilityArtifact`/`AuditVerdict` dataclasses enforce a strict information barrier between coder and verifier subagents.
-- **Recon-first `planner` subagent.** New read-only planner decomposes tasks into parallel seed descriptions via `<recon_seeds>` JSON for structured fan-out before workers start.
-- **`coder` artifact contract.** Structured `<coding_artifact>` handoff block at end of every coder response enables direct consumption by the `verifier` subagent.
+- **Quieter `/login`.** The login prompt handoff no longer emits a `RuntimeWarning` about an un-awaited `redraw_in_future` coroutine; the redraw throttle now uses a coroutine-free path.
+- **Alibaba `/usage` reporting.** A dedicated Alibaba usage adapter means an Alibaba login now produces a populated cost/quota panel instead of the no-adapter fallback.
+- **Live pricing from models.dev.** `/usage` and the session stats panel pull per-model pricing from the models.dev catalog (cached 24h) for more accurate cost estimates.
+- **More robust ripgrep resolution.** File search verifies a bundled `rg` can actually run on the host platform and architecture before using it, falling back to a system or freshly downloaded ripgrep otherwise.
 
-Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.37.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.38.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
 
 
 ---
@@ -214,7 +212,7 @@ matches your OS — no Python, Node, or `uv` prerequisite.
 
 | Platform | Recommended install | Artifact source |
 |---|---|---|
-| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.37.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
+| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.38.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> / <img src="https://img.shields.io/badge/-Linux-FCC624?style=flat-square&logo=linux&logoColor=black" alt="Linux">** | `curl -fsSL https://pythinker.com/install.sh \| bash` | native tarball from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> — Homebrew** | `brew install Pythoughts-labs/pythinker/pythinker-code` | auto-published Homebrew tap |
 | **🐳 Docker** | `docker run --rm -it ghcr.io/pythoughts-labs/pythinker-code` | GHCR multi-arch image |
@@ -242,7 +240,7 @@ pythinker                      # start the interactive TUI
 
 ### 🪟 Windows — native installer
 
-`PythinkerSetup-0.37.0.exe` is a signed* Inno Setup wizard. Installs per-user
+`PythinkerSetup-0.38.0.exe` is a signed* Inno Setup wizard. Installs per-user
 into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user
 PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see
 the change. **No UAC prompt.**
@@ -253,13 +251,13 @@ irm https://pythinker.com/install.ps1 | iex
 
 # Or manually download the installer + checksum from the Releases page,
 # verify with Get-FileHash, then run:
-.\PythinkerSetup-0.37.0.exe
+.\PythinkerSetup-0.38.0.exe
 
 # Open a fresh PowerShell
 pythinker --version
 ```
 
-**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.37.0.exe /ALLUSERS`
+**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.38.0.exe /ALLUSERS`
 installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin).
 
 **Upgrade:** `pythinker update` from inside the running app — it downloads
@@ -310,26 +308,26 @@ attached to every GitHub Release.
 
 ```sh
 # Debian / Ubuntu (x86_64)
-sudo dpkg -i pythinker-code_0.37.0_amd64.deb
+sudo dpkg -i pythinker-code_0.38.0_amd64.deb
 sudo apt-get install -f       # only if dpkg reports missing deps
 
 # Debian / Ubuntu (ARM64)
-sudo dpkg -i pythinker-code_0.37.0_arm64.deb
+sudo dpkg -i pythinker-code_0.38.0_arm64.deb
 
 # Fedora / RHEL / openSUSE (x86_64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.x86_64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.x86_64.rpm.sha256
-sha256sum -c pythinker-code-0.37.0.x86_64.rpm.sha256
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.x86_64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.x86_64.rpm.sha256
+sha256sum -c pythinker-code-0.38.0.x86_64.rpm.sha256
 # Fedora / RHEL:
-sudo dnf install ./pythinker-code-0.37.0.x86_64.rpm
+sudo dnf install ./pythinker-code-0.38.0.x86_64.rpm
 # openSUSE:
-sudo zypper install ./pythinker-code-0.37.0.x86_64.rpm
+sudo zypper install ./pythinker-code-0.38.0.x86_64.rpm
 
 # Fedora / RHEL (aarch64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.aarch64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.aarch64.rpm.sha256
-sha256sum -c pythinker-code-0.37.0.aarch64.rpm.sha256
-sudo dnf install ./pythinker-code-0.37.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.aarch64.rpm.sha256
+sha256sum -c pythinker-code-0.38.0.aarch64.rpm.sha256
+sudo dnf install ./pythinker-code-0.38.0.aarch64.rpm
 ```
 
 Both packages drop a small `/usr/bin/pythinker` launcher that execs the real
@@ -338,8 +336,8 @@ binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy.
 **Verify before install:**
 
 ```sh
-sha256sum -c pythinker-code_0.37.0_amd64.deb.sha256        # Debian/Ubuntu
-sha256sum -c pythinker-code-0.37.0.x86_64.rpm.sha256       # Fedora/RHEL
+sha256sum -c pythinker-code_0.38.0_amd64.deb.sha256        # Debian/Ubuntu
+sha256sum -c pythinker-code-0.38.0.x86_64.rpm.sha256       # Fedora/RHEL
 ```
 
 **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` /

{pythinker_code-0.37.0 → pythinker_code-0.38.0}/README.md

@@ -50,16 +50,14 @@ It speaks the [**Agent Client Protocol (ACP)**](https://github.com/agentclientpr
 
 ---
 
-## 🆕 What's New in 0.37.0
+## 🆕 What's New in 0.38.0
 
-- **Agent runtime tool visibility hardening.** `PythinkerToolset` now gates tool advertisements by execution policy, permission profile, root/subagent role, and plan-mode state — execution-time guards remain as defense in depth.
-- **Agent design upgrades.** New `ask` and `debug` primary agents selectable with `--agent`, a `scout` subagent for docs/API freshness research, richer spec metadata, and stable compaction summaries.
-- **Prompt-injection defense: `UntrustedData` wrapper.** External file and web content is wrapped in signed `<untrusted_data>` tags before reaching the LLM, with breakout-prevention escaping.
-- **Agent boundary artifacts.** Typed `CodingArtifact`/`VerificationResult` and `VulnerabilityArtifact`/`AuditVerdict` dataclasses enforce a strict information barrier between coder and verifier subagents.
-- **Recon-first `planner` subagent.** New read-only planner decomposes tasks into parallel seed descriptions via `<recon_seeds>` JSON for structured fan-out before workers start.
-- **`coder` artifact contract.** Structured `<coding_artifact>` handoff block at end of every coder response enables direct consumption by the `verifier` subagent.
+- **Quieter `/login`.** The login prompt handoff no longer emits a `RuntimeWarning` about an un-awaited `redraw_in_future` coroutine; the redraw throttle now uses a coroutine-free path.
+- **Alibaba `/usage` reporting.** A dedicated Alibaba usage adapter means an Alibaba login now produces a populated cost/quota panel instead of the no-adapter fallback.
+- **Live pricing from models.dev.** `/usage` and the session stats panel pull per-model pricing from the models.dev catalog (cached 24h) for more accurate cost estimates.
+- **More robust ripgrep resolution.** File search verifies a bundled `rg` can actually run on the host platform and architecture before using it, falling back to a system or freshly downloaded ripgrep otherwise.
 
-Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.37.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.38.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
 
 
 ---
@@ -149,7 +147,7 @@ matches your OS — no Python, Node, or `uv` prerequisite.
 
 | Platform | Recommended install | Artifact source |
 |---|---|---|
-| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.37.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
+| **🪟 Windows** | `irm https://pythinker.com/install.ps1 \| iex` | `PythinkerSetup-0.38.0.exe` from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> / <img src="https://img.shields.io/badge/-Linux-FCC624?style=flat-square&logo=linux&logoColor=black" alt="Linux">** | `curl -fsSL https://pythinker.com/install.sh \| bash` | native tarball from [Releases](https://github.com/Pythoughts-labs/pythinker-code/releases/latest) |
 | **<img src="https://img.shields.io/badge/-macOS-000000?style=flat-square&logo=apple&logoColor=white" alt="macOS"> — Homebrew** | `brew install Pythoughts-labs/pythinker/pythinker-code` | auto-published Homebrew tap |
 | **🐳 Docker** | `docker run --rm -it ghcr.io/pythoughts-labs/pythinker-code` | GHCR multi-arch image |
@@ -177,7 +175,7 @@ pythinker                      # start the interactive TUI
 
 ### 🪟 Windows — native installer
 
-`PythinkerSetup-0.37.0.exe` is a signed* Inno Setup wizard. Installs per-user
+`PythinkerSetup-0.38.0.exe` is a signed* Inno Setup wizard. Installs per-user
 into `%LOCALAPPDATA%\Programs\Pythinker`, registers `pythinker` on your user
 PATH (`HKCU\Environment`), broadcasts `WM_SETTINGCHANGE` so new shells see
 the change. **No UAC prompt.**
@@ -188,13 +186,13 @@ irm https://pythinker.com/install.ps1 | iex
 
 # Or manually download the installer + checksum from the Releases page,
 # verify with Get-FileHash, then run:
-.\PythinkerSetup-0.37.0.exe
+.\PythinkerSetup-0.38.0.exe
 
 # Open a fresh PowerShell
 pythinker --version
 ```
 
-**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.37.0.exe /ALLUSERS`
+**Per-machine install** (IT-managed boxes): `.\PythinkerSetup-0.38.0.exe /ALLUSERS`
 installs to `%ProgramFiles%\Pythinker` and writes PATH to HKLM (requires admin).
 
 **Upgrade:** `pythinker update` from inside the running app — it downloads
@@ -245,26 +243,26 @@ attached to every GitHub Release.
 
 ```sh
 # Debian / Ubuntu (x86_64)
-sudo dpkg -i pythinker-code_0.37.0_amd64.deb
+sudo dpkg -i pythinker-code_0.38.0_amd64.deb
 sudo apt-get install -f       # only if dpkg reports missing deps
 
 # Debian / Ubuntu (ARM64)
-sudo dpkg -i pythinker-code_0.37.0_arm64.deb
+sudo dpkg -i pythinker-code_0.38.0_arm64.deb
 
 # Fedora / RHEL / openSUSE (x86_64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.x86_64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.x86_64.rpm.sha256
-sha256sum -c pythinker-code-0.37.0.x86_64.rpm.sha256
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.x86_64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.x86_64.rpm.sha256
+sha256sum -c pythinker-code-0.38.0.x86_64.rpm.sha256
 # Fedora / RHEL:
-sudo dnf install ./pythinker-code-0.37.0.x86_64.rpm
+sudo dnf install ./pythinker-code-0.38.0.x86_64.rpm
 # openSUSE:
-sudo zypper install ./pythinker-code-0.37.0.x86_64.rpm
+sudo zypper install ./pythinker-code-0.38.0.x86_64.rpm
 
 # Fedora / RHEL (aarch64)
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.aarch64.rpm
-curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.37.0/pythinker-code-0.37.0.aarch64.rpm.sha256
-sha256sum -c pythinker-code-0.37.0.aarch64.rpm.sha256
-sudo dnf install ./pythinker-code-0.37.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.aarch64.rpm
+curl -LO https://github.com/Pythoughts-labs/pythinker-code/releases/download/v0.38.0/pythinker-code-0.38.0.aarch64.rpm.sha256
+sha256sum -c pythinker-code-0.38.0.aarch64.rpm.sha256
+sudo dnf install ./pythinker-code-0.38.0.aarch64.rpm
 ```
 
 Both packages drop a small `/usr/bin/pythinker` launcher that execs the real
@@ -273,8 +271,8 @@ binary under `/usr/lib/pythinker/`, so your `$PATH` stays tidy.
 **Verify before install:**
 
 ```sh
-sha256sum -c pythinker-code_0.37.0_amd64.deb.sha256        # Debian/Ubuntu
-sha256sum -c pythinker-code-0.37.0.x86_64.rpm.sha256       # Fedora/RHEL
+sha256sum -c pythinker-code_0.38.0_amd64.deb.sha256        # Debian/Ubuntu
+sha256sum -c pythinker-code-0.38.0.x86_64.rpm.sha256       # Fedora/RHEL
 ```
 
 **Upgrade:** download the new `.deb`/`.rpm` from Releases and `dpkg -i` /

{pythinker_code-0.37.0 → pythinker_code-0.38.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pythinker-code"
-version = "0.37.0"
+version = "0.38.0"
 description = "Pythinker — an agentic CLI developed by Pythoughts-labs."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -34,8 +34,11 @@ dependencies = [
     "pyyaml==6.0.3",
     "rich==15.0.0",
     "certifi>=2025.10.5",
-    "click==8.3.0",
     "pyperclip==1.11.0",
+    # Pinned: click 8.4.x regresses pyright (`click.Option` typed partially
+    # unknown, ~95 errors in `make check`). Unpin once that type regression is
+    # fixed upstream. Mirrored as a Dependabot ignore in .github/dependabot.yml.
+    "click==8.3.0",
     "streamingjson==0.0.5",
     "trafilatura==2.0.0",
     # lxml is used by trafilatura/htmldate/justext; keep pinned for binary wheels.
@@ -73,6 +76,9 @@ dev = [
     "pytest>=9.0.3",
     "pytest-asyncio>=1.3.0",
     "pytest-cov>=6.0",
+    # Pinned: ruff 0.15's formatter reflow fails `make check`. Unpin once the
+    # formatting churn is resolved. Mirrored as a Dependabot ignore in
+    # .github/dependabot.yml.
     "ruff>=0.14.10,<0.15",
 ]
 

{pythinker_code-0.37.0 → pythinker_code-0.38.0}/src/pythinker_code/CHANGELOG.md

@@ -15,6 +15,15 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+## 0.38.0 (2026-06-08)
+
+- **Quieter `/login`.** Logging in no longer prints a `RuntimeWarning` about an un-awaited `redraw_in_future` coroutine. The prompt redraw throttle now uses a coroutine-free path (`max_render_postpone_time`), eliminating the warning emitted during the login prompt handoff.
+- **Alibaba usage reporting.** `/usage` now ships a dedicated Alibaba adapter, so logging in with an Alibaba key produces a populated cost/quota panel instead of falling through to the no-adapter branch.
+- **Live model pricing from models.dev.** Cost estimates in `/usage` and the session stats panel now pull per-model input/output pricing from the models.dev catalog (fetched once and cached for 24 hours), improving cost accuracy across providers.
+- **More robust ripgrep resolution.** File search now verifies that a bundled `rg` binary can actually execute on the host platform and architecture before using it, falling back to a system or freshly downloaded ripgrep when the bundled one cannot run — fixing search failures on mismatched-architecture installs.
+
+Upgrade with `pythinker update`, `pip install --upgrade pythinker-code==0.38.0`, or use the native installer for your platform from the [Releases page](https://github.com/Pythoughts-labs/pythinker-code/releases/latest).
+
 ## 0.37.0 (2026-06-07)
 
 - **Agent runtime tool visibility hardening.** `PythinkerToolset` now filters the tools advertised to the model by active execution policy, permission profile, root/subagent role, and plan-mode state while preserving execution-time guards as defense in depth.

pythinker_code-0.38.0/src/pythinker_code/models_dev.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, cast
+
+import aiohttp
+
+from pythinker_code.utils.aiohttp import new_client_session
+from pythinker_code.utils.logging import logger
+
+_MODELS_DEV_URL = "https://models.dev/api.json"
+_TTL_SECONDS = 86_400  # 24 hours
+
+# Canonical providers win over regional/cloud variants when the same
+# bare model id appears under multiple providers.
+_CANONICAL_PROVIDERS = {
+    "anthropic",
+    "openai",
+    "google",
+    "deepseek",
+    "z-ai",
+    "moonshot",
+    "minimax",
+    "meta",
+    "mistral",
+    "cohere",
+    "x-ai",
+}
+
+# Module-level lock: only one network fetch runs at a time.
+_refresh_lock = asyncio.Lock()
+
+# In-process memo: (mtime_ns, catalog_dict)
+_catalog_cache: dict[str, Any] = {}
+
+
+@dataclass(frozen=True)
+class ModelPrice:
+    input: float  # USD / 1M tokens
+    output: float
+    cache_read: float  # 0.0 if absent
+    cache_write: float  # 0.0 if absent
+
+
+def _get_cache_path() -> Path:
+    """Return ~/.pythinker/model-pricing/models-dev.json (or $PYTHINKER_DIR variant)."""
+    base = Path(os.environ.get("PYTHINKER_DIR") or Path.home() / ".pythinker")
+    return base / "model-pricing" / "models-dev.json"
+
+
+def _coerce_cost(raw: object) -> float:
+    """Coerce a cost field to float; returns 0.0 for None, raises on non-numeric."""
+    if raw is None:
+        return 0.0
+    if isinstance(raw, (int, float, str)):
+        return float(raw)
+    raise TypeError(f"non-numeric cost value: {raw!r}")
+
+
+def _flatten_catalog(raw: dict[str, Any]) -> dict[str, ModelPrice]:
+    """Flatten provider→models hierarchy into {model_id: ModelPrice}.
+
+    Canonical providers win over regional/compat variants.
+    Model ids containing '@' (version-tagged) are excluded.
+    context_over_200k tiered pricing is ignored.
+    Models with any non-numeric cost field are skipped.
+    """
+    canonical: dict[str, ModelPrice] = {}
+    fallback: dict[str, ModelPrice] = {}
+
+    for provider_id, provider_data in raw.items():
+        if not isinstance(provider_data, dict):
+            continue
+        models = cast(dict[str, Any], provider_data).get("models")
+        if not isinstance(models, dict):
+            continue
+        target = canonical if provider_id in _CANONICAL_PROVIDERS else fallback
+        for model_id, model_data in sorted(cast(dict[str, Any], models).items()):
+            if "@" in model_id:
+                continue
+            if not isinstance(model_data, dict):
+                continue
+            cost = cast(dict[str, Any], model_data).get("cost")
+            if not isinstance(cost, dict):
+                continue
+            cost_map = cast(dict[str, Any], cost)
+            try:
+                price = ModelPrice(
+                    input=_coerce_cost(cost_map.get("input")),
+                    output=_coerce_cost(cost_map.get("output")),
+                    cache_read=_coerce_cost(cost_map.get("cache_read")),
+                    cache_write=_coerce_cost(cost_map.get("cache_write")),
+                )
+            except (TypeError, ValueError):
+                continue
+            if model_id not in target:
+                target[model_id] = price
+
+    merged = {**fallback, **canonical}
+    return merged
+
+
+def load_catalog() -> dict[str, ModelPrice]:
+    """Sync. Return flattened {model_id: ModelPrice} from disk cache.
+
+    Returns {} when no cache file exists or the file is unreadable/corrupt.
+    Memoises by file mtime_ns — re-parses only after a successful refresh.
+    """
+    cache_path = _get_cache_path()
+    try:
+        mtime_ns = cache_path.stat().st_mtime_ns
+    except OSError:
+        return {}
+
+    cached = _catalog_cache.get("entry")
+    if cached is not None and cached[0] == mtime_ns:
+        return cached[1]  # type: ignore[return-value]
+
+    try:
+        raw = json.loads(cache_path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+    # Valid-but-non-object JSON (e.g. a top-level list) must not escape the
+    # {} fallback contract — _flatten_catalog assumes a provider mapping.
+    if not isinstance(raw, dict):
+        return {}
+
+    result = _flatten_catalog(cast(dict[str, Any], raw))
+    _catalog_cache["entry"] = (mtime_ns, result)
+    return result
+
+
+async def _do_fetch(cache_path: Path) -> bool:
+    """Fetch models.dev/api.json and write it atomically to *cache_path*."""
+    tmp_path = cache_path.with_suffix(".tmp")
+    try:
+        async with (
+            new_client_session() as session,
+            session.get(
+                _MODELS_DEV_URL,
+                timeout=aiohttp.ClientTimeout(total=10),
+                raise_for_status=True,
+            ) as resp,
+        ):
+            text = await resp.text()
+        # Validate it's parseable JSON before writing.
+        json.loads(text)
+        cache_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp_path.write_text(text, encoding="utf-8")
+        os.replace(tmp_path, cache_path)
+        return True
+    except Exception as exc:
+        tmp_path.unlink(missing_ok=True)
+        logger.debug("models.dev fetch failed: {error}", error=exc)
+        return False
+
+
+async def refresh_catalog(*, force: bool = False) -> bool:
+    """Async. Fetch models.dev/api.json if cache is missing or stale (>24h).
+
+    Returns True when cache is valid (fresh or just refreshed), False on
+    network/write failure. Never raises.
+    """
+    cache_path = _get_cache_path()
+    if not force:
+        try:
+            age = time.time() - cache_path.stat().st_mtime
+            if age < _TTL_SECONDS:
+                return True
+        except OSError:
+            pass
+
+    async with _refresh_lock:
+        if not force:
+            try:
+                age = time.time() - cache_path.stat().st_mtime
+                if age < _TTL_SECONDS:
+                    return True
+            except OSError:
+                pass
+        return await _do_fetch(cache_path)