usage.py 3.3 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273
  1. """``hermes usage`` — the account-limits block of the REPL ``/usage`` without starting a session.
  2. Script-friendly Codex / Anthropic / OpenRouter quota view (issue #33094): same fetch and renderer as
  3. ``/usage`` (``agent.account_usage``), same credential resolution as a session with no live agent, plus
  4. ``--json`` for cron jobs and shell loops. Slim redo of #81819 (@himanusia).
  5. """
  6. from __future__ import annotations
  7. import argparse
  8. import json
  9. import sys
  10. def usage_snapshot_document(snapshot) -> dict:
  11. """``hermes usage --json`` document. Schema is documented in website/docs/reference/cli-commands.md —
  12. keep the keys stable; extend only by adding keys."""
  13. return {
  14. "provider": snapshot.provider,
  15. "source": snapshot.source,
  16. "title": snapshot.title,
  17. "plan": snapshot.plan,
  18. "fetched_at": snapshot.fetched_at.isoformat(),
  19. "windows": [
  20. {
  21. "label": window.label,
  22. "used_percent": window.used_percent,
  23. "resets_at": window.reset_at.isoformat() if window.reset_at else None,
  24. "detail": window.detail,
  25. }
  26. for window in snapshot.windows
  27. ],
  28. "details": list(snapshot.details),
  29. "unavailable_reason": snapshot.unavailable_reason,
  30. }
  31. def cmd_usage(args: argparse.Namespace) -> int:
  32. """Print the configured (or ``--provider``) account's usage windows; exit 1 when nothing could be fetched."""
  33. from agent.account_usage import fetch_account_usage, render_account_usage_lines
  34. from hermes_cli.runtime_provider import resolve_requested_provider
  35. provider = resolve_requested_provider(getattr(args, "provider", None))
  36. # No explicit key: the fetcher resolves the credential exactly as a session without a live agent
  37. # would (singleton store, then credential pool) — it never adopts or refreshes anything else.
  38. snapshot = fetch_account_usage(provider)
  39. if snapshot is None:
  40. print(
  41. f"No account usage available for provider '{provider}': no credential is configured for it, "
  42. "the provider has no usage endpoint, or the fetch failed.",
  43. file=sys.stderr,
  44. )
  45. return 1
  46. if getattr(args, "json", False):
  47. print(json.dumps(usage_snapshot_document(snapshot), indent=2))
  48. else:
  49. print("\n".join(render_account_usage_lines(snapshot)))
  50. return 0
  51. def build_usage_parser(subparsers) -> None:
  52. """Attach the ``usage`` subcommand to ``subparsers``."""
  53. usage_parser = subparsers.add_parser(
  54. "usage", help="Show account rate-limit windows (the /usage block) without starting a session",
  55. description="Fetch the configured provider's account limits (Codex 5h/weekly windows, plan, banked "
  56. "resets; Anthropic OAuth windows; OpenRouter credits) — the same block the /usage slash "
  57. "command prints — and exit. Exit code 1 when no credential is configured or the fetch fails.",
  58. )
  59. usage_parser.add_argument(
  60. "--provider", default=None, help="Provider to query (default: the configured model provider)")
  61. usage_parser.add_argument(
  62. "--json", action="store_true", help="Print one JSON document instead of the human-readable block")
  63. usage_parser.set_defaults(func=cmd_usage)