hermes-plugin-tinyfish 0.3.3__tar.gz → 0.3.4__tar.gz

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project uses semantic versioning.
 
 ## Unreleased
 
+## [0.3.4] - 2026-08-13
+
+### Fixed
+
+- Replaced `hermes tinyfish usage` request-history output with the actual
+  TinyFish wallet balance, auto-reload, pending top-up, and billing-rate API.
+  Legacy-billing accounts now receive a clear explanation instead of request
+  history, and the command states that no documented historical-spend API is
+  available.
+
 ## [0.3.3] - 2026-08-12
 
 ### Fixed

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hermes-plugin-tinyfish
-Version: 0.3.3
+Version: 0.3.4
 Summary: TinyFish Search, Fetch, plain-language routing, update awareness, and optional Browser for Hermes Agent
 Project-URL: Homepage, https://github.com/gabeosx/hermes-plugin-tinyfish
 Project-URL: Documentation, https://github.com/gabeosx/hermes-plugin-tinyfish#readme
@@ -300,10 +300,12 @@ hermes tinyfish doctor --live-paid
   present. It does not mean the access or refresh token is valid.
 - `/tinyfish-status` shows non-networked status inside CLI or gateway sessions;
   `/tinyfish-status live` explicitly runs Search and Fetch checks.
-- `usage` reads TinyFish Search and Fetch operation history independently and
-  prints a labeled, paginated history for people. Use `usage --json` for the raw
-  machine-readable response. It reports per-surface success or failure and is
-  not Agent or Browser billing data.
+- `usage` reads TinyFish's wallet API and reports the available balance,
+  auto-reload state, pending top-ups, and per-product billing rates. TinyFish
+  does not expose historical aggregate spend through its documented APIs. For
+  legacy-billing accounts without a Metronome wallet, the command explains why
+  balance data is unavailable and links to the billing dashboard. Use
+  `usage --json` for machine-readable output; request history is never dumped.
 - `doctor --live-paid` only creates and closes a TinyFish Browser session. It
   refuses under `deny`, requests approval under `request`, and never prints
   connection URLs or credentials.

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/README.md

@@ -268,10 +268,12 @@ hermes tinyfish doctor --live-paid
   present. It does not mean the access or refresh token is valid.
 - `/tinyfish-status` shows non-networked status inside CLI or gateway sessions;
   `/tinyfish-status live` explicitly runs Search and Fetch checks.
-- `usage` reads TinyFish Search and Fetch operation history independently and
-  prints a labeled, paginated history for people. Use `usage --json` for the raw
-  machine-readable response. It reports per-surface success or failure and is
-  not Agent or Browser billing data.
+- `usage` reads TinyFish's wallet API and reports the available balance,
+  auto-reload state, pending top-ups, and per-product billing rates. TinyFish
+  does not expose historical aggregate spend through its documented APIs. For
+  legacy-billing accounts without a Metronome wallet, the command explains why
+  balance data is unavailable and links to the billing dashboard. Use
+  `usage --json` for machine-readable output; request history is never dumped.
 - `doctor --live-paid` only creates and closes a TinyFish Browser session. It
   refuses under `deny`, requests approval under `request`, and never prints
   connection URLs or credentials.

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/hermes_plugin_tinyfish/rest_client.py

@@ -11,6 +11,7 @@ import httpx
 SEARCH_URL = "https://api.search.tinyfish.ai"
 FETCH_URL = "https://api.fetch.tinyfish.ai"
 BROWSER_URL = "https://api.browser.tinyfish.ai"
+WALLET_URL = "https://agent.tinyfish.ai/v1/wallet"
 SEARCH_USAGE_URL = f"{SEARCH_URL}/usage"
 FETCH_USAGE_URL = f"{FETCH_URL}/usage"
 
@@ -24,6 +25,10 @@ class TinyFishRestError(RuntimeError):
     """Raised for TinyFish REST transport or HTTP failures."""
 
 
+class TinyFishWalletNotFound(TinyFishRestError):
+    """Raised when an account uses legacy billing or has no wallet yet."""
+
+
 def _headers(api_key: str) -> dict[str, str]:
     return {"X-API-Key": api_key, "Accept": "application/json"}
 
@@ -237,7 +242,26 @@ def fetch_usage(*, api_key: str, timeout: float = 30.0) -> dict[str, Any]:
     )
 
 
+def wallet(*, api_key: str, timeout: float = 30.0) -> dict[str, Any]:
+    """Return the caller's TinyFish wallet balance and billing rates."""
+
+    try:
+        response = httpx.get(WALLET_URL, headers=_headers(api_key), timeout=timeout)
+        response.raise_for_status()
+        return cast(dict[str, Any], response.json())
+    except httpx.HTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            raise TinyFishWalletNotFound(
+                "TinyFish has no wallet for this account (legacy billing or no Metronome customer yet)."
+            ) from exc
+        _raise_http_error("TinyFish Wallet", exc)
+    except httpx.RequestError as exc:
+        raise TinyFishRestError(f"Could not reach TinyFish Wallet: {exc}") from exc
+    except ValueError as exc:
+        raise TinyFishRestError("TinyFish Wallet returned invalid JSON") from exc
+
+
 def usage(*, api_key: str, timeout: float = 30.0) -> dict[str, Any]:
-    """Compatibility wrapper for the Fetch usage endpoint."""
+    """Compatibility wrapper for the wallet-backed usage command."""
 
-    return fetch_usage(api_key=api_key, timeout=timeout)
+    return wallet(api_key=api_key, timeout=timeout)

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/hermes_plugin_tinyfish/setup_cli.py

@@ -6,7 +6,6 @@ import argparse
 import json
 import os
 import sys
-from collections.abc import Callable
 from pathlib import Path
 from typing import Any, cast
 
@@ -35,6 +34,7 @@ from .routing_context import tinyfish_mcp_configured
 from .update_check import InstallInfo, UpdateChecker
 
 MCP_LOGIN_COMMAND = ("hermes", "mcp", "login", "tinyfish")
+TINYFISH_BILLING_URL = "https://agent.tinyfish.ai/api-keys"
 
 
 def setup_tinyfish_cli(parser: argparse.ArgumentParser) -> None:
@@ -86,7 +86,7 @@ def setup_tinyfish_cli(parser: argparse.ArgumentParser) -> None:
     credits_set.add_argument("policy", choices=list(CREDIT_POLICIES))
     credits_sub.add_parser("reset", help="Reset Browser to deny and remove retired Agent/Profile policy keys")
 
-    usage = sub.add_parser("usage", help="Read TinyFish Search and Fetch operation history")
+    usage = sub.add_parser("usage", help="Read TinyFish wallet balance and billing rates")
     usage.add_argument("--json", action="store_true", help="Print machine-readable JSON")
 
 
@@ -702,133 +702,64 @@ def cmd_credits(args: argparse.Namespace) -> int:
     return 2
 
 
-def _usage_surface(
-    reader: Callable[..., dict[str, Any]],
-    *,
-    api_key: str,
-) -> dict[str, Any]:
-    try:
-        return {"success": True, "data": reader(api_key=api_key)}
-    except Exception as exc:  # noqa: BLE001
-        return {"success": False, "error": str(exc)}
-
-
-_USAGE_FIELD_ORDER = (
-    "created_at",
-    "status",
-    "query",
-    "url",
-    "final_url",
-    "title",
-    "description",
-    "domain_type",
-    "location",
-    "language",
-    "author",
-    "published_date",
-    "format",
-    "results_count",
-    "total_results",
-    "text_length",
-    "links_count",
-    "image_links_count",
-    "latency_ms",
-    "request_origin",
-    "id",
-    "request_id",
-    "error",
-)
-
-_USAGE_FIELD_LABELS = {
-    "id": "ID",
-    "url": "URL",
-    "final_url": "Final URL",
-    "latency_ms": "Latency (ms)",
-    "request_id": "Request ID",
-}
-
+def _wallet_amount(value: Any, currency: Any) -> str:
+    amount = str(value) if value is not None else "unavailable"
+    code = str(currency or "").strip()
+    if amount == "unavailable":
+        return amount
+    if code == "USD":
+        return f"${amount} USD"
+    return f"{amount} {code}".rstrip()
 
-def _usage_field_label(key: str) -> str:
-    return _USAGE_FIELD_LABELS.get(key, key.replace("_", " ").capitalize())
 
+def _wallet_text_lines(wallet: dict[str, Any]) -> list[str]:
+    currency = wallet.get("currency")
+    lines = [
+        "TinyFish usage",
+        f"  Available balance: {_wallet_amount(wallet.get('available_balance'), currency)}",
+        f"  As of: {wallet.get('as_of') or 'unavailable'}",
+    ]
 
-def _usage_value_lines(value: Any) -> list[str]:
-    if value is None:
-        return ["-"]
-    if isinstance(value, bool):
-        return ["yes" if value else "no"]
-    if isinstance(value, list) and all(
-        item is None or isinstance(item, (str, int, float, bool)) for item in value
-    ):
-        return [", ".join(str(item) for item in value) if value else "-"]
-    if isinstance(value, (dict, list)):
-        return json.dumps(value, indent=2, sort_keys=True, ensure_ascii=False).splitlines()
-    return [str(value)]
-
-
-def _usage_items(data: dict[str, Any]) -> list[Any]:
-    for key in ("items", "operations"):
-        value = data.get(key)
-        if isinstance(value, list):
-            return value
-    return []
-
-
-def _usage_summary(data: dict[str, Any], *, shown: int) -> str:
-    noun = "operation" if shown == 1 else "operations"
-    parts = [f"{shown} {noun}"]
-    total = data.get("total")
-    if isinstance(total, int) and not isinstance(total, bool):
-        parts[0] = f"{shown} shown / {total} total"
-    page = data.get("page")
-    total_pages = data.get("total_pages")
-    if isinstance(page, int) and isinstance(total_pages, int):
-        parts.append(f"page {page} of {total_pages}")
-    limit = data.get("limit")
-    if isinstance(limit, int) and not isinstance(limit, bool):
-        parts.append(f"limit {limit}")
-    if isinstance(data.get("has_more"), bool):
-        parts.append(f"more: {'yes' if data['has_more'] else 'no'}")
-    return " | ".join(parts)
-
-
-def _usage_text_lines(payload: dict[str, Any]) -> list[str]:
-    lines = ["TinyFish usage"]
-    surfaces = payload.get("surfaces")
-    if not isinstance(surfaces, dict):
-        return [*lines, "  Invalid usage response."]
-
-    for surface_name in ("search", "fetch"):
-        lines.extend(("", surface_name.capitalize()))
-        result = surfaces.get(surface_name)
-        if not isinstance(result, dict):
-            lines.append("  No response.")
-            continue
-        if not result.get("success"):
-            lines.append(f"  Error: {result.get('error') or 'Unknown error'}")
-            continue
-
-        data = result.get("data")
-        if not isinstance(data, dict):
-            lines.append("  Invalid usage response.")
-            continue
-        items = _usage_items(data)
-        lines.append(f"  {_usage_summary(data, shown=len(items))}")
-        if not items:
-            lines.append("  No operations found on this page.")
-            continue
-
-        for index, item in enumerate(items, start=1):
-            lines.extend(("", f"  Operation {index}"))
-            if not isinstance(item, dict):
-                lines.append(f"    Value: {_usage_value_lines(item)[0]}")
+    auto_reload = wallet.get("auto_reload")
+    if auto_reload is None:
+        lines.append("  Auto-reload: unavailable")
+    elif isinstance(auto_reload, dict):
+        state = str(auto_reload.get("state") or "unknown").replace("_", " ")
+        if state == "unconfigured":
+            lines.append("  Auto-reload: not configured")
+        else:
+            threshold = _wallet_amount(auto_reload.get("threshold"), currency)
+            recharge_to = _wallet_amount(auto_reload.get("recharge_to"), currency)
+            lines.append(f"  Auto-reload: {state} (at {threshold}, recharge to {recharge_to})")
+    else:
+        lines.append("  Auto-reload: invalid response")
+
+    pending = wallet.get("pending_top_up")
+    if pending is None:
+        lines.append("  Pending top-up: none")
+    elif isinstance(pending, dict):
+        amount = _wallet_amount(pending.get("amount"), currency)
+        lines.append(f"  Pending top-up: {amount} since {pending.get('started_at') or 'unknown'}")
+    else:
+        lines.append("  Pending top-up: invalid response")
+
+    rates = wallet.get("rates")
+    meters = rates.get("meters") if isinstance(rates, dict) else None
+    if isinstance(meters, list) and meters:
+        lines.append("  Rates:")
+        for meter in meters:
+            if not isinstance(meter, dict):
                 continue
-            ordered_keys = [key for key in _USAGE_FIELD_ORDER if key in item]
-            ordered_keys.extend(sorted(str(key) for key in item if key not in ordered_keys))
-            for key in ordered_keys:
-                value_lines = _usage_value_lines(item[key])
-                lines.append(f"    {_usage_field_label(key)}: {value_lines[0]}")
-                lines.extend(f"      {line}" for line in value_lines[1:])
+            label = meter.get("label") or meter.get("product_id") or "Unnamed meter"
+            amount = _wallet_amount(meter.get("unit_amount"), meter.get("currency"))
+            per = f" per {meter['per']}" if meter.get("per") else ""
+            lines.append(f"    {label}: {amount}{per}")
+    elif rates is None:
+        lines.append("  Rates: unavailable")
+    else:
+        lines.append("  Rates: none")
+
+    lines.append("  Historical spend: not provided by TinyFish's documented APIs")
     return lines
 
 
@@ -836,16 +767,39 @@ def cmd_usage(args: argparse.Namespace) -> int:
     api_key = _api_key_or_error()
     if not api_key:
         return 1
-    surfaces = {
-        "search": _usage_surface(rest_client.search_usage, api_key=api_key),
-        "fetch": _usage_surface(rest_client.fetch_usage, api_key=api_key),
-    }
-    payload = {
-        "success": all(result["success"] for result in surfaces.values()),
-        "surfaces": surfaces,
-    }
+    try:
+        wallet = rest_client.wallet(api_key=api_key)
+    except rest_client.TinyFishWalletNotFound:
+        payload = {
+            "success": True,
+            "wallet_available": False,
+            "reason": "legacy_billing_or_no_metronome_customer",
+            "message": "This account uses legacy billing or does not have a Metronome wallet yet.",
+            "billing_url": TINYFISH_BILLING_URL,
+        }
+        text_lines = [
+            "TinyFish usage",
+            "  Wallet balance unavailable.",
+            f"  {payload['message']}",
+            "  Historical spend is not provided by TinyFish's documented APIs.",
+            f"  Billing: {TINYFISH_BILLING_URL}",
+        ]
+    except Exception as exc:  # noqa: BLE001
+        payload = {"success": False, "wallet_available": None, "error": str(exc)}
+        text_lines = ["TinyFish usage", f"  Error: {exc}"]
+    else:
+        if not isinstance(wallet, dict):
+            payload = {
+                "success": False,
+                "wallet_available": None,
+                "error": "TinyFish Wallet returned an invalid response",
+            }
+            text_lines = ["TinyFish usage", f"  Error: {payload['error']}"]
+        else:
+            payload = {"success": True, "wallet_available": True, "wallet": wallet}
+            text_lines = _wallet_text_lines(wallet)
     if bool(getattr(args, "json", False)):
         print(json.dumps(payload, indent=2, sort_keys=True))
     else:
-        print("\n".join(_usage_text_lines(payload)))
+        print("\n".join(text_lines))
     return 0 if payload["success"] else 1

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/plugin.yaml

@@ -1,5 +1,5 @@
 name: web-tinyfish
-version: 0.3.3
+version: 0.3.4
 description: "Independent TinyFish provider plugin for Hermes Agent. Adds MCP-first Search/Fetch, plain-language tool routing, update awareness, and optional default-deny Browser infrastructure."
 author: gabeosx
 kind: backend

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hermes-plugin-tinyfish"
-version = "0.3.3"
+version = "0.3.4"
 description = "TinyFish Search, Fetch, plain-language routing, update awareness, and optional Browser for Hermes Agent"
 readme = "README.md"
 requires-python = ">=3.10"

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/tests/test_rest_client.py

@@ -183,16 +183,55 @@ def test_search_usage_uses_documented_search_endpoint(monkeypatch: pytest.Monkey
     }
 
 
-def test_usage_is_a_compatibility_wrapper(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_wallet_uses_documented_endpoint(monkeypatch: pytest.MonkeyPatch) -> None:
     captured: dict[str, Any] = {}
 
-    def fake_fetch_usage(*, api_key: str, timeout: float) -> dict[str, Any]:
+    def fake_get(url: str, **kwargs: Any) -> httpx.Response:
+        captured.update(url=url, **kwargs)
+        return _response("GET", url, payload={"available_balance": "12.34", "currency": "USD"})
+
+    monkeypatch.setattr(rest_client.httpx, "get", fake_get)
+
+    result = rest_client.wallet(api_key="tf_test", timeout=13.0)
+
+    assert result == {"available_balance": "12.34", "currency": "USD"}
+    assert captured == {
+        "url": "https://agent.tinyfish.ai/v1/wallet",
+        "headers": {"X-API-Key": "tf_test", "Accept": "application/json"},
+        "timeout": 13.0,
+    }
+
+
+def test_wallet_reports_documented_not_found_account_state(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    def fake_get(url: str, **kwargs: Any) -> httpx.Response:
+        return _response(
+            "GET",
+            url,
+            status=404,
+            payload={"error": {"code": "NOT_FOUND", "message": "Wallet not found"}},
+        )
+
+    monkeypatch.setattr(rest_client.httpx, "get", fake_get)
+
+    with pytest.raises(
+        rest_client.TinyFishWalletNotFound,
+        match="legacy billing or no Metronome customer yet",
+    ):
+        rest_client.wallet(api_key="tf_test")
+
+
+def test_usage_is_a_wallet_compatibility_wrapper(monkeypatch: pytest.MonkeyPatch) -> None:
+    captured: dict[str, Any] = {}
+
+    def fake_wallet(*, api_key: str, timeout: float) -> dict[str, Any]:
         captured.update(api_key=api_key, timeout=timeout)
-        return {"operations": []}
+        return {"available_balance": "12.34"}
 
-    monkeypatch.setattr(rest_client, "fetch_usage", fake_fetch_usage)
+    monkeypatch.setattr(rest_client, "wallet", fake_wallet)
 
-    assert rest_client.usage(api_key="tf_test", timeout=14.0) == {"operations": []}
+    assert rest_client.usage(api_key="tf_test", timeout=14.0) == {"available_balance": "12.34"}
     assert captured == {"api_key": "tf_test", "timeout": 14.0}
 
 
@@ -211,6 +250,7 @@ RestCall = Callable[[], dict[str, Any]]
         ),
         ("get", lambda: rest_client.search_usage(api_key="tf_test"), "TinyFish Search usage"),
         ("get", lambda: rest_client.fetch_usage(api_key="tf_test"), "TinyFish Fetch usage"),
+        ("get", lambda: rest_client.wallet(api_key="tf_test"), "TinyFish Wallet"),
     ],
 )
 @pytest.mark.parametrize("status", [402, 500])
@@ -245,6 +285,7 @@ def test_rest_methods_report_http_failures(
         ),
         ("get", lambda: rest_client.search_usage(api_key="tf_test"), "TinyFish Search usage"),
         ("get", lambda: rest_client.fetch_usage(api_key="tf_test"), "TinyFish Fetch usage"),
+        ("get", lambda: rest_client.wallet(api_key="tf_test"), "TinyFish Wallet"),
     ],
 )
 def test_rest_methods_report_transport_failures(
@@ -274,6 +315,7 @@ def test_rest_methods_report_transport_failures(
         ),
         ("get", lambda: rest_client.search_usage(api_key="tf_test"), "TinyFish Search usage"),
         ("get", lambda: rest_client.fetch_usage(api_key="tf_test"), "TinyFish Fetch usage"),
+        ("get", lambda: rest_client.wallet(api_key="tf_test"), "TinyFish Wallet"),
     ],
 )
 def test_rest_methods_report_invalid_json(

{hermes_plugin_tinyfish-0.3.3 → hermes_plugin_tinyfish-0.3.4}/tests/test_setup_cli.py

@@ -715,86 +715,55 @@ def test_credits_reset_removes_retired_keys_and_leaves_browser_denied(
     assert saved[-1]["tinyfish"]["credit_policy"] == {"browser": "deny"}
 
 
-def test_usage_calls_search_and_fetch_usage(
+def test_usage_calls_wallet_and_returns_machine_readable_billing_data(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
-    calls: list[tuple[str, str]] = []
+    calls: list[str] = []
     monkeypatch.setattr(cli, "_get_env", lambda name: "tf_secret")
 
-    def search_usage(*, api_key: str) -> dict[str, Any]:
-        calls.append(("search", api_key))
-        return {"items": [{"status": "completed"}]}
+    def wallet(*, api_key: str) -> dict[str, Any]:
+        calls.append(api_key)
+        return {"available_balance": "21.44", "currency": "USD"}
 
-    def fetch_usage(*, api_key: str) -> dict[str, Any]:
-        calls.append(("fetch", api_key))
-        return {"operations": [{"status": "completed"}]}
-
-    monkeypatch.setattr(cli.rest_client, "search_usage", search_usage)
-    monkeypatch.setattr(cli.rest_client, "fetch_usage", fetch_usage)
+    monkeypatch.setattr(cli.rest_client, "wallet", wallet)
 
     result = cli.cmd_usage(argparse.Namespace(json=True))
     payload = json.loads(capsys.readouterr().out)
 
     assert result == 0
-    assert calls == [("search", "tf_secret"), ("fetch", "tf_secret")]
+    assert calls == ["tf_secret"]
     assert payload == {
         "success": True,
-        "surfaces": {
-            "search": {
-                "success": True,
-                "data": {"items": [{"status": "completed"}]},
-            },
-            "fetch": {
-                "success": True,
-                "data": {"operations": [{"status": "completed"}]},
-            },
-        },
+        "wallet_available": True,
+        "wallet": {"available_balance": "21.44", "currency": "USD"},
     }
     assert "tf_secret" not in json.dumps(payload)
 
 
-def test_usage_text_output_formats_operation_history_for_people(
+def test_usage_text_output_formats_wallet_for_people(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     monkeypatch.setattr(cli, "_get_env", lambda name: "tf_secret")
     monkeypatch.setattr(
         cli.rest_client,
-        "search_usage",
-        lambda *, api_key: {
-            "items": [
-                {
-                    "id": "search-1",
-                    "query": "Hermes Agent",
-                    "status": "completed",
-                    "results_count": 10,
-                    "latency_ms": 125,
-                    "created_at": "2026-08-12T20:00:00Z",
-                }
-            ],
-            "total": 3,
-            "limit": 1,
-            "page": 1,
-            "total_pages": 3,
-            "has_more": True,
-        },
-    )
-    monkeypatch.setattr(
-        cli.rest_client,
-        "fetch_usage",
+        "wallet",
         lambda *, api_key: {
-            "operations": [
-                {
-                    "url": "https://example.com",
-                    "status": "failed",
-                    "error": "timeout",
-                    "created_at": "2026-08-12T20:01:00Z",
-                }
-            ],
-            "total": 1,
-            "limit": 100,
-            "page": 1,
-            "total_pages": 1,
-            "has_more": False,
+            "available_balance": "21.44",
+            "currency": "USD",
+            "as_of": "2026-08-13T12:00:00Z",
+            "auto_reload": {"state": "on", "threshold": "10.00", "recharge_to": "50.00"},
+            "pending_top_up": {"amount": "50.00", "started_at": "2026-08-13T11:59:00Z"},
+            "rates": {
+                "meters": [
+                    {
+                        "product_id": "prod_agent",
+                        "label": "Agent steps",
+                        "unit_amount": "0.016000",
+                        "currency": "USD",
+                        "per": "step",
+                    }
+                ]
+            },
         },
     )
 
@@ -805,92 +774,89 @@ def test_usage_text_output_formats_operation_history_for_people(
     assert (
         output
         == """TinyFish usage
-
-Search
-  1 shown / 3 total | page 1 of 3 | limit 1 | more: yes
-
-  Operation 1
-    Created at: 2026-08-12T20:00:00Z
-    Status: completed
-    Query: Hermes Agent
-    Results count: 10
-    Latency (ms): 125
-    ID: search-1
-
-Fetch
-  1 shown / 1 total | page 1 of 1 | limit 100 | more: no
-
-  Operation 1
-    Created at: 2026-08-12T20:01:00Z
-    Status: failed
-    URL: https://example.com
-    Error: timeout
+  Available balance: $21.44 USD
+  As of: 2026-08-13T12:00:00Z
+  Auto-reload: on (at $10.00 USD, recharge to $50.00 USD)
+  Pending top-up: $50.00 USD since 2026-08-13T11:59:00Z
+  Rates:
+    Agent steps: $0.016000 USD per step
+  Historical spend: not provided by TinyFish's documented APIs
 """
     )
-    assert "{'" not in output
     assert "tf_secret" not in output
+    assert "query" not in output.lower()
+    assert "url" not in output.lower()
 
 
-def test_usage_text_output_keeps_partial_failure_readable(
+def test_usage_wallet_not_found_explains_legacy_billing(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     monkeypatch.setattr(cli, "_get_env", lambda name: "tf_secret")
-    monkeypatch.setattr(cli.rest_client, "search_usage", lambda *, api_key: {"items": []})
 
-    def fail_usage(*, api_key: str) -> dict[str, Any]:
-        raise RuntimeError("usage unavailable")
+    def wallet_not_found(*, api_key: str) -> dict[str, Any]:
+        raise cli.rest_client.TinyFishWalletNotFound("wallet not found")
 
-    monkeypatch.setattr(cli.rest_client, "fetch_usage", fail_usage)
+    monkeypatch.setattr(cli.rest_client, "wallet", wallet_not_found)
 
     result = cli.cmd_usage(argparse.Namespace(json=False))
     output = capsys.readouterr().out
 
-    assert result == 1
-    assert "Search\n  0 operations\n  No operations found on this page." in output
-    assert "Fetch\n  Error: usage unavailable" in output
+    assert result == 0
+    assert "Wallet balance unavailable" in output
+    assert "legacy billing or does not have a Metronome wallet" in output
+    assert "Historical spend is not provided" in output
+    assert cli.TINYFISH_BILLING_URL in output
 
 
-def test_usage_partial_failure_returns_both_surface_results_and_failure(
+def test_usage_wallet_not_found_is_machine_readable(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     monkeypatch.setattr(cli, "_get_env", lambda name: "tf_secret")
-    monkeypatch.setattr(
-        cli.rest_client,
-        "search_usage",
-        lambda *, api_key: {"items": [{"status": "completed"}]},
-    )
 
-    def fail_usage(*, api_key: str) -> dict[str, Any]:
-        raise RuntimeError("usage unavailable")
+    def wallet_not_found(*, api_key: str) -> dict[str, Any]:
+        raise cli.rest_client.TinyFishWalletNotFound("wallet not found")
+
+    monkeypatch.setattr(cli.rest_client, "wallet", wallet_not_found)
+
+    result = cli.cmd_usage(argparse.Namespace(json=True))
+    payload = json.loads(capsys.readouterr().out)
+
+    assert result == 0
+    assert payload == {
+        "success": True,
+        "wallet_available": False,
+        "reason": "legacy_billing_or_no_metronome_customer",
+        "message": "This account uses legacy billing or does not have a Metronome wallet yet.",
+        "billing_url": cli.TINYFISH_BILLING_URL,
+    }
+
 
-    monkeypatch.setattr(cli.rest_client, "fetch_usage", fail_usage)
+def test_usage_transport_failure_is_reported_without_history(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(cli, "_get_env", lambda name: "tf_secret")
+
+    def fail_wallet(*, api_key: str) -> dict[str, Any]:
+        raise cli.rest_client.TinyFishRestError("Could not reach TinyFish Wallet")
+
+    monkeypatch.setattr(cli.rest_client, "wallet", fail_wallet)
 
     result = cli.cmd_usage(argparse.Namespace(json=True))
     payload = json.loads(capsys.readouterr().out)
 
     assert result == 1
-    assert payload["success"] is False
-    assert payload["surfaces"]["search"]["success"] is True
-    assert payload["surfaces"]["fetch"] == {
+    assert payload == {
         "success": False,
-        "error": "usage unavailable",
+        "wallet_available": None,
+        "error": "Could not reach TinyFish Wallet",
     }
 
 
-def test_usage_without_api_key_fails_before_calling_usage_endpoints(
+def test_usage_without_api_key_fails_before_calling_wallet(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
     monkeypatch.setattr(cli, "_get_env", lambda name: "")
-    monkeypatch.setattr(
-        cli.rest_client,
-        "search_usage",
-        lambda **kwargs: pytest.fail("Search usage must not be called"),
-    )
-    monkeypatch.setattr(
-        cli.rest_client,
-        "fetch_usage",
-        lambda **kwargs: pytest.fail("Fetch usage must not be called"),
-    )
+    monkeypatch.setattr(cli.rest_client, "wallet", lambda **kwargs: pytest.fail("Wallet must not be called"))
 
     result = cli.cmd_usage(argparse.Namespace(json=True))
     captured = capsys.readouterr()