account_usage.py 49 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975
  1. from __future__ import annotations
  2. import logging
  3. import math
  4. import time
  5. from dataclasses import dataclass, replace
  6. from datetime import UTC, datetime
  7. from typing import TYPE_CHECKING, Any, Callable, Optional
  8. import httpx
  9. from agent.anthropic_credentials import _is_oauth_token, resolve_anthropic_token
  10. from hermes_cli.auth import AuthError, _read_codex_tokens, resolve_codex_runtime_credentials
  11. from hermes_cli.auth_codex import _codex_pool_route_base_url
  12. from hermes_cli.runtime_provider import resolve_runtime_provider
  13. from hermes_time import safe_strftime
  14. from agent.usage_gauges import BP_FULL
  15. if TYPE_CHECKING:
  16. from typing import TypeGuard
  17. logger = logging.getLogger(__name__)
  18. _DEPLETED_LINE = "Status: access depleted — top up to restore"
  19. # Usage-window plans: allowances are shown as percent used.
  20. _WINDOW_TOP_TIER_USED_UP = "Monthly large-model usage is used up."
  21. _WINDOW_PAUSED_LINE = ("Status: included usage paused. Your subscription payment failed. Update your card to restore it. "
  22. "Until then, Hermes uses your credits.")
  23. _WINDOW_PAUSED_OTHER_LINE = "Status: included usage paused. See Billing in the Portal. Until then, Hermes uses your credits."
  24. def _utc_now() -> datetime:
  25. return datetime.now(UTC)
  26. @dataclass(frozen=True)
  27. class AccountUsageWindow:
  28. label: str
  29. used_percent: Optional[float] = None
  30. reset_at: Optional[datetime] = None
  31. detail: Optional[str] = None
  32. # ``account``: exhausting this window exhausts the whole login (Codex session/weekly).
  33. # ``model``: the window caps only one model family (Anthropic Opus/Sonnet weekly) and can
  34. # never imply the account itself is out of quota.
  35. scope: str = "account"
  36. @dataclass(frozen=True)
  37. class AccountUsageSnapshot:
  38. provider: str
  39. source: str
  40. fetched_at: datetime
  41. title: str = "Account limits"
  42. plan: Optional[str] = None
  43. windows: tuple[AccountUsageWindow, ...] = ()
  44. details: tuple[str, ...] = ()
  45. unavailable_reason: Optional[str] = None
  46. # Stable account identity of the credential the snapshot was fetched with (e.g. a decoded
  47. # Codex JWT principal), when the provider supports one. Never a secret; ``None`` = the
  48. # fetcher cannot tell accounts apart, so the snapshot belongs to the provider's legacy slot.
  49. identity: Optional[str] = None
  50. # Exact decoded provider response body (no headers/credentials) for integrations that need
  51. # fields Hermes does not normalize yet. Only populated by providers that fetch a JSON body.
  52. raw: Optional[dict] = None
  53. # Usage-window plans only: the stacked bar layout. Every other snapshot
  54. # renders exactly as before.
  55. usage_window: bool = False
  56. @property
  57. def available(self) -> bool:
  58. return bool(self.windows or self.details) and not self.unavailable_reason
  59. def _snapshot(provider: str, source: str, windows: list, details: list, **kw: Any) -> AccountUsageSnapshot:
  60. return AccountUsageSnapshot(provider=provider, source=source, fetched_at=_utc_now(), windows=tuple(windows), details=tuple(details), **kw)
  61. def _title_case_slug(value: Optional[str]) -> Optional[str]:
  62. cleaned = str(value or "").strip()
  63. return cleaned.replace("_", " ").replace("-", " ").title() if cleaned else None
  64. def _parse_dt(value: Any) -> Optional[datetime]:
  65. if value in {None, ""}:
  66. return None
  67. if isinstance(value, (int, float)):
  68. return datetime.fromtimestamp(float(value), tz=UTC)
  69. if not isinstance(value, str) or not (text := value.strip()):
  70. return None
  71. text = text[:-1] + "+00:00" if text.endswith("Z") else text
  72. try:
  73. dt = datetime.fromisoformat(text)
  74. return dt if dt.tzinfo else dt.replace(tzinfo=UTC)
  75. except ValueError:
  76. return None
  77. def _format_reset(dt: Optional[datetime]) -> str:
  78. if not dt:
  79. return "unknown"
  80. stamp = safe_strftime(dt.astimezone(), "%Y-%m-%d %H:%M %Z")
  81. total_seconds = int((dt - _utc_now()).total_seconds())
  82. if total_seconds <= 0:
  83. return f"now ({stamp})"
  84. hours, rem = divmod(total_seconds, 3600)
  85. minutes = rem // 60
  86. if hours >= 24:
  87. days, hours = divmod(hours, 24)
  88. return f"in {days}d {hours}h ({stamp})"
  89. return f"in {hours}h {minutes}m ({stamp})" if hours else f"in {minutes}m ({stamp})"
  90. def _reset_phrase(dt: Optional[datetime]) -> str:
  91. """``resets in 23h`` — no wall-clock stamp (those wrap and collide in the TUI)."""
  92. if not dt:
  93. return "resets soon"
  94. try:
  95. from hermes_cli.model_picker_usage import format_resets_in
  96. return format_resets_in(int(dt.timestamp() * 1000))
  97. except Exception:
  98. logger.debug("Reset phrase formatting failed", exc_info=True)
  99. return f"resets {_format_reset(dt)}"
  100. def render_account_usage_lines(snapshot: Optional[AccountUsageSnapshot], *, markdown: bool = False) -> list[str]:
  101. if not snapshot:
  102. return []
  103. if snapshot.usage_window:
  104. return _render_usage_window_lines(snapshot)
  105. bold = "**" if markdown else ""
  106. plan = f" ({snapshot.plan})" if snapshot.plan else ""
  107. lines = [f"📈 {bold}{snapshot.title}{bold}", f"Provider: {snapshot.provider}{plan}"]
  108. for window in snapshot.windows:
  109. if window.used_percent is None:
  110. base = f"{window.label}: unavailable"
  111. else:
  112. used = float(window.used_percent)
  113. base = f"{window.label}: {max(0, round(100 - used))}% remaining ({max(0, round(used))}% used)"
  114. if window.reset_at:
  115. base += f" • resets {_format_reset(window.reset_at)}"
  116. elif window.detail:
  117. base += f" • {window.detail}"
  118. lines.append(base)
  119. lines.extend(snapshot.details)
  120. if snapshot.unavailable_reason:
  121. lines.append(f"Unavailable: {snapshot.unavailable_reason}")
  122. return lines
  123. def _render_usage_window_lines(snapshot: AccountUsageSnapshot) -> list[str]:
  124. """Usage-window plans: plain stacked bar lines for CLI ``/usage`` and the TUI panel. No emoji,
  125. no ANSI, no markdown — Ink ``<Text>`` would otherwise count escape bytes as width and smear the wrap."""
  126. if snapshot.plan:
  127. lines = [snapshot.plan]
  128. else:
  129. lines = [snapshot.title, f"Provider: {snapshot.provider}"]
  130. label_w = max((len(window.label) for window in snapshot.windows), default=0)
  131. for window in snapshot.windows:
  132. label = f"{window.label:<{label_w}}" if label_w else window.label
  133. if window.used_percent is None:
  134. base = f"{label} unavailable"
  135. else:
  136. used = max(0.0, min(100.0, float(window.used_percent))) / 100.0
  137. try:
  138. from hermes_cli.model_picker_usage import format_percent_used, render_bar
  139. bar, pct = render_bar(used), format_percent_used(used)
  140. except Exception:
  141. logger.debug("Usage bar rendering failed", exc_info=True)
  142. bar, pct = "", f"{int(used * 100)}%"
  143. base = f"{label} {bar} {pct} used" if bar else f"{label} {pct} used"
  144. if window.reset_at:
  145. base += f" · {_reset_phrase(window.reset_at)}"
  146. elif window.detail:
  147. base += f" · {window.detail}"
  148. lines.append(base)
  149. lines.extend(snapshot.details)
  150. if snapshot.unavailable_reason:
  151. lines.append(f"Unavailable: {snapshot.unavailable_reason}")
  152. return lines
  153. def _fmt_usd(d: float) -> str:
  154. return f"${d:,.2f}"
  155. def _is_num(v: Any) -> TypeGuard[float]:
  156. return isinstance(v, (int, float))
  157. def _is_finite_num(v: Any) -> TypeGuard[float]:
  158. """True iff v is a real number (int/float, not bool, not NaN/Inf); TypeGuard so callers can do arithmetic."""
  159. return _is_num(v) and not isinstance(v, bool) and math.isfinite(v)
  160. def _nous_snapshot(windows: list, details: list, tail: list, *, source: str, plan: Optional[str] = None,
  161. usage_window: bool = False) -> Optional[AccountUsageSnapshot]:
  162. """Nous snapshot with *tail* lines appended, or None when there is nothing to show."""
  163. if not windows and not details:
  164. return None
  165. return _snapshot("nous", source, windows, details + tail, title="Nous credits", plan=plan, usage_window=usage_window)
  166. def _bp_window(label: str, used_bp: Any, resets_at_ms: Any) -> Optional[AccountUsageWindow]:
  167. """One usage-window gauge row from basis points + an epoch-ms reset (already bounded by
  168. ``usage_gauges.parse_gauges``); None when the percent is not an int. An unknown reset keeps the row,
  169. shown without a reset."""
  170. if isinstance(used_bp, bool) or not isinstance(used_bp, int):
  171. return None
  172. known = isinstance(resets_at_ms, int) and not isinstance(resets_at_ms, bool)
  173. reset_at = datetime.fromtimestamp(resets_at_ms / 1000, tz=UTC) if known else None
  174. return AccountUsageWindow(label=label, used_percent=max(0.0, min(100.0, used_bp / BP_FULL * 100.0)),
  175. reset_at=reset_at)
  176. def _window_top_tier_line(reset_at: Optional[datetime], keep_going_on_credits: Any = None) -> str:
  177. """``Monthly large-model usage is used up. Resets Nov 3. Past this, large models use your credits.`` (local
  178. date). With Keep going on credits off, credits don't unlock it, so the line points at the other included models."""
  179. resets = ""
  180. if isinstance(reset_at, datetime):
  181. local = reset_at.astimezone()
  182. resets = f" Resets {local:%b} {local.day}."
  183. tail = " Your other included usage is still available." if keep_going_on_credits is False else " Past this, large models use your credits."
  184. return f"{_WINDOW_TOP_TIER_USED_UP}{resets}{tail}"
  185. _WINDOW_KEEP_GOING_OFF_LINE = "Keep going on credits: off. Hermes waits for the reset (turn on in /topup)."
  186. _WINDOW_KEEP_GOING_ON_LINE = "Keep going on credits: on. Uses your credits when included usage runs out."
  187. def _usage_window_rows(gauges: Any, *, paused_reason: Any,
  188. keep_going_on_credits: Any = None) -> tuple[list[AccountUsageWindow], list[str]]:
  189. """One row per server allowance, in the server's order, plus the top-tier, payment-paused and top-up-off
  190. lines. Empty unless the list has an allowance that stops every model. ``keep_going_on_credits``: the
  191. account setting (None: an older server)."""
  192. from agent.usage_gauges import SCOPE_TOP_TIER, all_scope, gauge_title, parse_gauges
  193. parsed = parse_gauges(gauges)
  194. if not parsed or not all_scope(parsed):
  195. return [], []
  196. out: list[AccountUsageWindow] = []
  197. top_row: Optional[AccountUsageWindow] = None
  198. top_full = False
  199. for g in parsed:
  200. row = _bp_window(gauge_title(g), g.used_bp, g.resets_at_ms)
  201. if row is None:
  202. continue
  203. out.append(row)
  204. if g.scope == SCOPE_TOP_TIER:
  205. top_row, top_full = row, g.full
  206. lines: list[str] = []
  207. if top_full:
  208. lines.append(_window_top_tier_line(top_row.reset_at if top_row else None, keep_going_on_credits))
  209. if isinstance(paused_reason, str) and paused_reason:
  210. from agent.usage_gauges import paused_for_payment
  211. lines.append(_WINDOW_PAUSED_LINE if paused_for_payment(paused_reason) else _WINDOW_PAUSED_OTHER_LINE)
  212. elif keep_going_on_credits is False:
  213. lines.append(_WINDOW_KEEP_GOING_OFF_LINE)
  214. elif keep_going_on_credits is True:
  215. lines.append(_WINDOW_KEEP_GOING_ON_LINE)
  216. return out, lines
  217. def build_nous_credits_snapshot(account_info) -> Optional[AccountUsageSnapshot]:
  218. """NousPortalAccountInfo → /usage snapshot: dollar magnitudes + renewal date + portal CTA, plus a ``% used``
  219. gauge when the portal supplies ``monthly_credits``. A usage-window account (``usage_window`` present) shows
  220. its allowances as percent used, the large-model line and its top-up balance instead. Fail-open → None."""
  221. try:
  222. from hermes_cli.nous_account import nous_portal_topup_url
  223. if account_info is None or not getattr(account_info, "logged_in", False):
  224. return None
  225. access = getattr(account_info, "paid_service_access_info", None)
  226. sub = getattr(account_info, "subscription", None)
  227. windows: list[AccountUsageWindow] = []
  228. details: list[str] = []
  229. uw = getattr(account_info, "usage_window", None)
  230. if uw is not None:
  231. windows, window_lines = _usage_window_rows(
  232. getattr(uw, "gauges", None), paused_reason=getattr(uw, "paused_reason", None),
  233. keep_going_on_credits=getattr(uw, "keep_going_on_credits", None),
  234. )
  235. if windows: # usage-window account: percents, plus the top-up balance
  236. details.extend(window_lines)
  237. topup = getattr(access, "purchased_credits_remaining", None) if access is not None else None
  238. if _is_finite_num(topup):
  239. details.append(f"Top-up credits: {_fmt_usd(topup)}")
  240. if getattr(account_info, "paid_service_access", None) is False and not window_lines:
  241. details.append(_DEPLETED_LINE)
  242. if sub is not None and (period_end := getattr(sub, "current_period_end", None)):
  243. from agent.billing_usage import format_renews
  244. details.append(f"Renews: {format_renews(period_end) or period_end}")
  245. return _nous_snapshot(windows, details, ["Top up via /topup"], source="portal-account",
  246. plan=getattr(sub, "plan", None) if sub is not None else None, usage_window=True)
  247. # Gauge needs a positive cap AND a finite remaining <= cap (numeric fields, NOT a server *_usd); used =
  248. # cap - remaining clamped [0,100] so debt reads 100%. NaN/Inf (json.loads accepts bare NaN → "$nan") and
  249. # remaining > cap (rollover makes the cap a meaningless denominator) fall back to the magnitudes lines.
  250. if sub is not None:
  251. cap = getattr(sub, "monthly_credits", None)
  252. sub_remaining = getattr(sub, "credits_remaining", None)
  253. if _is_finite_num(cap) and cap > 0 and _is_finite_num(sub_remaining) and sub_remaining <= cap:
  254. windows.append(AccountUsageWindow(
  255. label="Subscription", used_percent=max(0.0, min(100.0, (cap - sub_remaining) / cap * 100.0)),
  256. detail=f"{_fmt_usd(sub_remaining)} of {_fmt_usd(cap)} left",
  257. ))
  258. if access is not None:
  259. for attr, label in (("subscription_credits_remaining", "Subscription credits"),
  260. ("purchased_credits_remaining", "Top-up credits"), ("total_usable_credits", "Total usable")):
  261. value = getattr(access, attr, None)
  262. if _is_finite_num(value):
  263. details.append(f"{label}: {_fmt_usd(value)}")
  264. if sub is not None:
  265. rollover = getattr(sub, "rollover_credits", None)
  266. if _is_finite_num(rollover) and rollover > 0:
  267. details.append(f"Rollover: {_fmt_usd(rollover)}")
  268. period_end = getattr(sub, "current_period_end", None)
  269. if period_end:
  270. details.append(f"Renews: {period_end}")
  271. if getattr(account_info, "paid_service_access", None) is False:
  272. details.append(_DEPLETED_LINE)
  273. return _nous_snapshot(windows, details, [f"Top up: {nous_portal_topup_url(account_info)}", "(or run /topup)"],
  274. source="portal-account", plan=getattr(sub, "plan", None) if sub is not None else None)
  275. except (AttributeError, TypeError):
  276. return None
  277. def _nous_logged_in() -> bool:
  278. """Cheap local auth-state check: a Nous access token is present. Fail-open False."""
  279. try:
  280. from hermes_cli.auth import get_provider_auth_state
  281. tok = (get_provider_auth_state("nous") or {}).get("access_token")
  282. return isinstance(tok, str) and bool(tok.strip())
  283. except Exception:
  284. return False
  285. def _fetch_portal_account(timeout: float):
  286. """Wall-clock-bounded fresh portal account fetch (raises on any failure/timeout).
  287. No ``with`` block on purpose: ``Executor.__exit__`` joins the worker via
  288. ``shutdown(wait=True)``, so a portal that accepts the connection but never
  289. answers would hold the caller until the provider's own timeout instead of
  290. ``timeout``. The abandoned daemon worker runs on to its own network timeout
  291. and never blocks the caller or process exit; its eventual exception is
  292. drained so GC never logs "exception was never retrieved"."""
  293. import contextvars
  294. from hermes_cli.nous_account import get_nous_portal_account_info
  295. from tools.daemon_pool import DaemonThreadPoolExecutor
  296. context = contextvars.copy_context()
  297. pool = DaemonThreadPoolExecutor(max_workers=1)
  298. future = pool.submit(context.run, get_nous_portal_account_info, force_fresh=True)
  299. try:
  300. return future.result(timeout=timeout)
  301. except BaseException:
  302. future.add_done_callback(lambda f: f.exception())
  303. raise
  304. finally:
  305. pool.shutdown(wait=False)
  306. def _header_gauge_percent(bp: Any) -> Optional[float]:
  307. if isinstance(bp, bool) or not isinstance(bp, int):
  308. return None
  309. return max(0.0, min(100.0, bp / BP_FULL * 100.0))
  310. def apply_header_gauge(snapshot: Optional[AccountUsageSnapshot], credits_state: Any) -> Optional[AccountUsageSnapshot]:
  311. """Raise window percents to the last response headers when those are ahead of the portal.
  312. The portal counter waits on spend-log ingestion. The headers already include finished included
  313. calls, and a large-model call that drew top-up reports that allowance full."""
  314. if snapshot is None or not snapshot.usage_window or credits_state is None:
  315. return snapshot
  316. if not getattr(credits_state, "from_header", False) or not getattr(credits_state, "is_usage_window", False):
  317. return snapshot
  318. # Row title → (header used bp, that gauge's reset). A header from before its gauge reset describes the
  319. # old window: the portal's fresh number stands.
  320. from agent.usage_gauges import gauge_title
  321. mapping = {gauge_title(g): (g.used_bp, g.resets_at_ms) for g in getattr(credits_state, "gauges", ()) or ()}
  322. now_ms = int(time.time() * 1000)
  323. windows: list[AccountUsageWindow] = []
  324. changed = False
  325. for window in snapshot.windows:
  326. bp, resets_at_ms = mapping.get(window.label, (None, None))
  327. stale = isinstance(resets_at_ms, int) and not isinstance(resets_at_ms, bool) and now_ms >= resets_at_ms
  328. header = None if stale else _header_gauge_percent(bp)
  329. current = window.used_percent
  330. if header is None or current is None or header <= float(current):
  331. windows.append(window)
  332. continue
  333. changed = True
  334. windows.append(replace(window, used_percent=header))
  335. if not changed:
  336. return snapshot
  337. details = snapshot.details
  338. top_gauge = getattr(credits_state, "top_tier_gauge", None)
  339. top = next((w for w in windows if top_gauge is not None and w.label == gauge_title(top_gauge)), None)
  340. if top is not None and (top.used_percent or 0) >= 100:
  341. if not any(line.startswith(_WINDOW_TOP_TIER_USED_UP) for line in details):
  342. details = details + (_window_top_tier_line(top.reset_at, getattr(credits_state, "keep_going_on_credits", None)),)
  343. return replace(snapshot, windows=tuple(windows), details=details)
  344. def nous_credits_lines(*, markdown: bool = False, timeout: float = 10.0, credits_state: Any = None) -> list[str]:
  345. """Rendered Nous-credits /usage lines, or [] when there's nothing to show. Independent of any live agent
  346. (logged-in gate, then a bounded portal fetch); shared by CLI ``_show_usage`` and the TUI ``session.usage`` RPC.
  347. Fail-open: any hiccup or timeout → []. HERMES_DEV_CREDITS_FIXTURE renders from the fixture instead of the portal.
  348. ``credits_state`` is the last response's header gauge; when it is ahead of the portal, the bars use it."""
  349. return nous_credits_view(markdown=markdown, timeout=timeout, credits_state=credits_state)[0]
  350. def nous_credits_view(*, markdown: bool = False, timeout: float = 10.0, credits_state: Any = None) -> tuple[list[str], bool]:
  351. """``nous_credits_lines`` plus whether they are the usage-window layout (callers keep today's
  352. presentation for everyone else). Fail-open → ``([], False)``."""
  353. try:
  354. from agent.credits_tracker import dev_fixture_credits_state
  355. fixture = dev_fixture_credits_state()
  356. except Exception:
  357. logger.debug("Dev credits fixture unavailable", exc_info=True)
  358. fixture = None
  359. if fixture is not None:
  360. snapshot = _snapshot_from_credits_state(fixture)
  361. return render_account_usage_lines(snapshot, markdown=markdown), bool(snapshot and snapshot.usage_window)
  362. if not _nous_logged_in():
  363. return [], False
  364. try:
  365. snapshot = apply_header_gauge(
  366. build_nous_credits_snapshot(_fetch_portal_account(timeout)), credits_state,
  367. )
  368. return render_account_usage_lines(snapshot, markdown=markdown), bool(snapshot and snapshot.usage_window)
  369. except Exception:
  370. # Fail-open; breadcrumb so a dead /usage credits block is diagnosable.
  371. logger.debug("credits ▸ /usage portal fetch/render failed (fail-open)", exc_info=True)
  372. return [], False
  373. def nous_credits_usage_fields(agent: Any = None) -> dict[str, Any]:
  374. """The ``session.usage`` fields for the Nous credits block: ``credits_lines`` (when there are any) and
  375. ``credits_usage_window`` for the usage-window layout. Reads *agent*'s live credits headers. Never raises."""
  376. try:
  377. lines, is_window = nous_credits_view(credits_state=getattr(agent, "_credits_state", None) if agent else None)
  378. except Exception:
  379. logger.debug("credits ▸ /usage fields unavailable", exc_info=True)
  380. return {}
  381. return ({"credits_lines": lines} | ({"credits_usage_window": True} if is_window else {})) if lines else {}
  382. def _snapshot_from_credits_state(state) -> Optional[AccountUsageSnapshot]:
  383. """Header-shaped CreditsState (dev fixture) → /usage snapshot, same shape as the portal path. *_usd strings
  384. are display-only; the % comes from CreditsState.used_fraction. Fail-open → None."""
  385. try:
  386. if state is None:
  387. return None
  388. windows: list[AccountUsageWindow] = []
  389. details: list[str] = []
  390. if getattr(state, "is_usage_window", False):
  391. windows, window_lines = _usage_window_rows(
  392. state.gauges, paused_reason=state.paused_reason,
  393. keep_going_on_credits=getattr(state, "keep_going_on_credits", None),
  394. )
  395. details.extend(window_lines)
  396. if getattr(state, "purchased_usd", None):
  397. details.append(f"Top-up credits: ${state.purchased_usd}")
  398. if getattr(state, "paid_access", True) is False and not window_lines:
  399. details.append(_DEPLETED_LINE)
  400. return _nous_snapshot(windows, details, ["(dev fixture — HERMES_DEV_CREDITS_FIXTURE)"], source="dev-fixture",
  401. usage_window=True)
  402. uf = getattr(state, "used_fraction", None)
  403. sub_usd = getattr(state, "subscription_usd", None)
  404. cap_usd = getattr(state, "subscription_limit_usd", None)
  405. if _is_num(uf) and math.isfinite(uf):
  406. windows.append(AccountUsageWindow(
  407. label="Subscription", used_percent=max(0.0, min(100.0, uf * 100.0)),
  408. detail=f"${sub_usd} of ${cap_usd} left" if sub_usd and cap_usd else None,
  409. ))
  410. for value, label in ((sub_usd, "Subscription credits"), (getattr(state, "purchased_usd", None), "Top-up credits"),
  411. (getattr(state, "remaining_usd", None), "Total usable")):
  412. if value:
  413. details.append(f"{label}: ${value}")
  414. if getattr(state, "paid_access", True) is False:
  415. details.append(_DEPLETED_LINE)
  416. return _nous_snapshot(windows, details, ["(dev fixture — HERMES_DEV_CREDITS_FIXTURE)"], source="dev-fixture")
  417. except (AttributeError, TypeError):
  418. return None
  419. @dataclass(frozen=True)
  420. class CreditsView:
  421. """Surface-agnostic ``/topup`` balance view: one portal fetch, consumed identically by every money surface.
  422. Fail-open: not logged in / portal unreachable → ``logged_in`` False, ``topup_url`` None."""
  423. logged_in: bool
  424. balance_lines: tuple[str, ...] = ()
  425. identity_line: Optional[str] = None
  426. topup_url: Optional[str] = None
  427. depleted: bool = False
  428. def build_credits_view(*, markdown: bool = False, timeout: float = 10.0) -> CreditsView:
  429. """/topup view: balance block + identity line + top-up URL. Reuses the /usage fetch + snapshot so numbers
  430. match; the balance block drops the trailing top-up/hint lines (/topup has its own affordance).
  431. Fail-open → ``CreditsView(logged_in=False)``."""
  432. not_logged_in = CreditsView(logged_in=False)
  433. if not _nous_logged_in():
  434. return not_logged_in
  435. try:
  436. account = _fetch_portal_account(timeout)
  437. except Exception:
  438. logger.debug("credits ▸ /topup portal fetch failed (fail-open)", exc_info=True)
  439. return not_logged_in
  440. if account is None or not getattr(account, "logged_in", False):
  441. return not_logged_in
  442. from hermes_cli.nous_account import nous_portal_topup_url
  443. balance_lines = [
  444. line
  445. for line in render_account_usage_lines(build_nous_credits_snapshot(account), markdown=markdown)
  446. if not line.lstrip().startswith(("Top up:", "Top up via", "(or run"))
  447. ]
  448. who = [str(v) for v in (getattr(account, "email", None),) if v]
  449. org_name = getattr(account, "org_name", None)
  450. if org_name:
  451. who.append(f"org {org_name}")
  452. return CreditsView(
  453. logged_in=True, balance_lines=tuple(balance_lines),
  454. identity_line=("Topping up as " + " / ".join(who)) if who else None, topup_url=nous_portal_topup_url(account),
  455. depleted=getattr(account, "paid_service_access", None) is False,
  456. )
  457. def _codex_backend_urls(base_url: str) -> tuple[str, str, str]:
  458. """Codex backend endpoints (usage, reset-credits list, consume). Mirrors the Codex CLI's PathStyle
  459. split: ``/backend-api`` bases use the ChatGPT ``/wham/`` paths; everything else ``/api/codex/``."""
  460. normalized = (base_url or "").strip().rstrip("/") or "https://chatgpt.com/backend-api/codex"
  461. normalized = normalized.removesuffix("/codex")
  462. prefix = normalized + ("/wham" if "/backend-api" in normalized else "/api/codex")
  463. return (prefix + "/usage", prefix + "/rate-limit-reset-credits", prefix + "/rate-limit-reset-credits/consume")
  464. def _resolve_codex_usage_credentials(
  465. base_url: Optional[str], api_key: Optional[str], *, force_refresh: bool = False,
  466. ) -> tuple[str, str, Optional[str]]:
  467. """Codex quota credentials: explicit live-agent creds → native runtime resolver (itself pool-aware) → direct
  468. pool select. Native OAuth stores device-code logins in the pool, so the singleton store alone is not enough."""
  469. explicit_key = str(api_key or "").strip()
  470. if explicit_key and not force_refresh:
  471. return explicit_key, str(base_url or "").strip(), None
  472. if explicit_key:
  473. # Forced retry for a live agent's own credential: refresh THAT credential (singleton or the
  474. # pool entry that issued it), never re-resolve — that would render another pool account's usage.
  475. try:
  476. singleton_key = str((_read_codex_tokens().get("tokens") or {}).get("access_token", "") or "").strip()
  477. except AuthError:
  478. singleton_key = ""
  479. if singleton_key != explicit_key:
  480. from agent.credential_pool import load_pool
  481. entry = load_pool("openai-codex").try_refresh_matching(api_key_hint=explicit_key)
  482. if entry is None:
  483. raise RuntimeError("Could not refresh the Codex credential this session runs on")
  484. return entry.runtime_api_key, _codex_pool_route_base_url(entry.runtime_base_url or base_url), None
  485. # Only AuthError is caught so tier 3 can run: a broad except would mask a transient refresh/network failure
  486. # and hand back a DIFFERENT pool account's usage; such errors must propagate to the fail-open outer guard.
  487. # account_id is best-effort: a partial singleton store must not sink a usable credential.
  488. try:
  489. # Tier 2: the native runtime resolver. It ALREADY falls back to the credential pool when the
  490. # singleton is empty (see ``resolve_codex_runtime_credentials`` — issue #32992), so in a pool-only
  491. # setup this returns a usable ``source="credential_pool"`` token. A refresh/network error must
  492. # propagate — the outer ``fetch_account_usage`` guard fails open (shows nothing this turn) rather
  493. # than reporting the wrong account.
  494. resolve_kwargs = {"refresh_if_expiring": True}
  495. if force_refresh:
  496. resolve_kwargs["force_refresh"] = True
  497. creds = resolve_codex_runtime_credentials(**resolve_kwargs)
  498. account_id: Optional[str] = None
  499. try:
  500. tokens = _read_codex_tokens().get("tokens") or {}
  501. account_id = str(tokens.get("account_id", "") or "").strip() or None
  502. except AuthError:
  503. # Pool-only creds carry no singleton account_id; header is optional.
  504. logger.debug("codex ▸ /usage account_id read failed (best-effort)", exc_info=True)
  505. return creds["api_key"], str(creds.get("base_url", "") or "").strip(), account_id
  506. except AuthError:
  507. logger.debug("codex ▸ /usage runtime resolver returned no creds; trying pool", exc_info=True)
  508. # Tier 3: pool credentials have no account_id concept → header omitted.
  509. from agent.credential_pool import load_pool
  510. entry = load_pool("openai-codex").select()
  511. if entry is None:
  512. raise RuntimeError("No available openai-codex credential in credential pool")
  513. # Pool rows keep the canonical URL; a gateway key must go to its route host, not chatgpt.com (#121486).
  514. return entry.runtime_api_key, _codex_pool_route_base_url(entry.runtime_base_url or base_url), None
  515. def _codex_banked_resets(payload: dict) -> int:
  516. raw = (payload.get("rate_limit_reset_credits") or {}).get("available_count")
  517. return int(raw) if _is_num(raw) else 0
  518. def _codex_headers(token: str, account_id: Optional[str]) -> dict[str, str]:
  519. """auth.json's ``account_id`` wins over the JWT claim; the JWT still supplies the residency header."""
  520. from agent.codex_headers import codex_account_headers
  521. return {"Authorization": f"Bearer {token}", "Accept": "application/json", "User-Agent": "codex-cli",
  522. **codex_account_headers(token), **({"ChatGPT-Account-ID": account_id} if account_id else {})}
  523. def _get_json(url: str, headers: dict[str, str], *, timeout: float) -> dict:
  524. with httpx.Client(timeout=timeout) as client:
  525. response = client.get(url, headers=headers)
  526. response.raise_for_status()
  527. return response.json() or {}
  528. def _usage_windows(
  529. source: dict, mapping: tuple[tuple[str, str], ...], used_key: str, reset_key: str, *, fraction: bool = False,
  530. model_scoped: frozenset[str] | set[str] = frozenset(),
  531. ) -> list[AccountUsageWindow]:
  532. """Build windows from ``source[key][used_key]``; ``fraction`` scales values <= 1 to percent.
  533. ``model_scoped`` keys build windows that cap only a model family, never the account."""
  534. windows: list[AccountUsageWindow] = []
  535. for key, label in mapping:
  536. window = source.get(key) or {}
  537. used = window.get(used_key)
  538. if used is None:
  539. continue
  540. used = float(used)
  541. if fraction and used <= 1:
  542. used *= 100
  543. windows.append(AccountUsageWindow(
  544. label=label, used_percent=used, reset_at=_parse_dt(window.get(reset_key)),
  545. scope="model" if key in model_scoped else "account",
  546. ))
  547. return windows
  548. # Published Codex quota windows by ``limit_window_seconds``: 5h session and 7-day weekly.
  549. _CODEX_WINDOW_LABELS_BY_SECONDS = {18000: "Session", 604800: "Weekly"}
  550. _CODEX_WINDOW_POSITIONAL_LABELS = (("primary_window", "Session"), ("secondary_window", "Weekly"))
  551. def _codex_window_labels(rate_limit: dict) -> tuple[tuple[str, str], ...]:
  552. """Label Codex windows by their published duration, not response position (#65387).
  553. The usage API keys windows ``primary_window``/``secondary_window`` by position; when only the
  554. weekly limit is returned it occupies ``primary_window`` and the positional mapping mislabeled it
  555. ``Session``. Windows whose ``limit_window_seconds`` is missing or unrecognized keep the legacy
  556. positional label so duration-less payloads render exactly as before.
  557. """
  558. labels = []
  559. for key, fallback in _CODEX_WINDOW_POSITIONAL_LABELS:
  560. window = rate_limit.get(key) or {}
  561. seconds = window.get("limit_window_seconds") if isinstance(window, dict) else None
  562. label = _CODEX_WINDOW_LABELS_BY_SECONDS.get(int(seconds), fallback) if _is_num(seconds) else fallback
  563. labels.append((key, label))
  564. return tuple(labels)
  565. def _plural(count: int) -> str:
  566. return "s" if count != 1 else ""
  567. def _fetch_codex_account_usage(
  568. base_url: Optional[str] = None, api_key: Optional[str] = None,
  569. ) -> Optional[AccountUsageSnapshot]:
  570. return _fetch_codex_account_usage_impl(base_url, api_key, read_only=False)
  571. def _fetch_codex_account_usage_read_only(
  572. base_url: Optional[str] = None, api_key: Optional[str] = None,
  573. ) -> Optional[AccountUsageSnapshot]:
  574. """Picker-cache variant: a 401 is reported, never repaired. The live-agent path
  575. (``_fetch_codex_account_usage``) retries via a forced credential refresh because the
  576. session it serves owns that credential; a per-credential read of the pool must NOT
  577. rotate, refresh or mutate anything — it just marks that account unknown."""
  578. return _fetch_codex_account_usage_impl(base_url, api_key, read_only=True)
  579. def _fetch_codex_account_usage_impl(
  580. base_url: Optional[str] = None, api_key: Optional[str] = None, *, read_only: bool = False,
  581. ) -> Optional[AccountUsageSnapshot]:
  582. token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
  583. try:
  584. payload = _get_json(
  585. _codex_backend_urls(resolved_base_url)[0], _codex_headers(token, account_id), timeout=15.0,
  586. )
  587. except httpx.HTTPStatusError as exc:
  588. if exc.response.status_code != 401:
  589. raise
  590. if read_only:
  591. # Never refresh/rotate on the picker's read-only path — surface the failure.
  592. raise
  593. token, resolved_base_url, account_id = _resolve_codex_usage_credentials(
  594. base_url, api_key, force_refresh=True,
  595. )
  596. payload = _get_json(
  597. _codex_backend_urls(resolved_base_url)[0], _codex_headers(token, account_id), timeout=15.0,
  598. )
  599. rate_limit = payload.get("rate_limit") or {}
  600. windows = _usage_windows(rate_limit, _codex_window_labels(rate_limit), "used_percent", "reset_at")
  601. details: list[str] = []
  602. count = _codex_banked_resets(payload)
  603. if count > 0:
  604. details.append(f"You have {count} reset{_plural(count)} banked - use /usage reset to activate")
  605. credits, balance = payload.get("credits") or {}, (payload.get("credits") or {}).get("balance")
  606. if credits.get("has_credits") and _is_num(balance):
  607. details.append(f"Credits balance: ${float(balance):.2f}")
  608. elif credits.get("has_credits") and credits.get("unlimited"):
  609. details.append("Credits balance: unlimited")
  610. return _snapshot("openai-codex", "usage_api", windows, details, plan=_title_case_slug(payload.get("plan_type")),
  611. identity=_codex_snapshot_identity(token), raw=payload)
  612. def _codex_snapshot_identity(token: str) -> Optional[str]:
  613. """Trusted per-account identity of a Codex credential: the decoded JWT principal
  614. (``chatgpt_account_id`` + ``sub``), never the token itself. Two credentials for one
  615. workspace member share it, so pool accounts are counted once, honestly."""
  616. from agent.credential_pool import _codex_principal_identity
  617. principal = _codex_principal_identity(token)
  618. return f"codex:{principal[0]}:{principal[1]}" if principal else None
  619. @dataclass(frozen=True)
  620. class CodexResetRedeemResult:
  621. """Outcome of a `/usage reset` attempt against the Codex backend."""
  622. status: str # reset|nothing_to_reset|no_credit|already_redeemed|not_exhausted|no_credits_banked|unavailable
  623. message: str
  624. available_count: int = 0
  625. windows_reset: int = 0
  626. @property
  627. def redeemed(self) -> bool:
  628. return self.status == "reset"
  629. # Client-side guard: a window only counts as exhausted when fully used; below this, redeeming a banked reset
  630. # wastes most of its value → block, point at --force.
  631. _CODEX_WINDOW_EXHAUSTED_PERCENT = 100.0
  632. def _unavailable(message: str) -> CodexResetRedeemResult:
  633. return CodexResetRedeemResult(status="unavailable", message=message)
  634. def _codex_reset_guard(payload: dict, available: int, force: bool) -> Optional[CodexResetRedeemResult]:
  635. """Refuse a redemption that would be wasted (no banked credits, or no window fully used and not ``force``)."""
  636. if available <= 0:
  637. return CodexResetRedeemResult(status="no_credits_banked", message="No banked reset credits on this account — nothing to redeem.")
  638. rate_limit = payload.get("rate_limit") or {}
  639. used_pcts = [float(u) for u in ((rate_limit.get(k) or {}).get("used_percent") for k in ("primary_window", "secondary_window"))
  640. if _is_num(u)]
  641. worst_used: Optional[float] = max(0.0, *used_pcts) if used_pcts else None
  642. if force or (worst_used is not None and worst_used >= _CODEX_WINDOW_EXHAUSTED_PERCENT):
  643. return None
  644. usage_note = (f"your busiest window is only {worst_used:.0f}% used" if worst_used is not None
  645. else "your current usage could not be confirmed as exhausted")
  646. return CodexResetRedeemResult(
  647. status="not_exhausted", available_count=available,
  648. message=(f"⚠️ Not redeeming: {usage_note}. A banked reset restores your FULL 5h + weekly limits, so spending it "
  649. f"now would waste most of it. You have {available} reset{_plural(available)} banked. "
  650. f"Use `/usage reset --force` to redeem anyway."),
  651. )
  652. def _codex_reset_outcome(body: dict, available: int) -> CodexResetRedeemResult:
  653. """Map the consume response ``code`` to a result (``reset`` also lifts persisted pool cooldowns)."""
  654. code = str(body.get("code", "") or "").strip().lower()
  655. remaining = max(0, available - 1)
  656. outcomes: dict[str, tuple[str, int]] = {
  657. "reset": (f"✅ Reset redeemed — your usage limits have been reset. {remaining} banked reset{_plural(remaining)} remaining.",
  658. remaining),
  659. "nothing_to_reset": ("Backend reports nothing to reset — your limits aren't exhausted. The credit was NOT spent.", available),
  660. "no_credit": ("Backend reports no available reset credit on this account.", 0),
  661. "already_redeemed": ("This redemption was already processed — no additional credit was spent.", remaining),
  662. }
  663. if code not in outcomes:
  664. return _unavailable(f"Unexpected response from the Codex backend: {body!r}")
  665. windows_reset = 0
  666. if code == "reset":
  667. # Quota is restored upstream — lift persisted pool cooldowns so the credential isn't frozen behind a
  668. # stale ``last_error_reset_at``.
  669. try:
  670. from hermes_cli.auth import clear_codex_pool_quota_cooldowns
  671. clear_codex_pool_quota_cooldowns()
  672. except Exception:
  673. logger.debug("Failed to clear Codex pool cooldowns after reset redemption", exc_info=True)
  674. raw = body.get("windows_reset")
  675. windows_reset = int(raw) if _is_num(raw) else 0
  676. message, count = outcomes[code]
  677. return CodexResetRedeemResult(status=code, message=message, available_count=count, windows_reset=windows_reset)
  678. def redeem_codex_reset_credit(
  679. *, base_url: Optional[str] = None, api_key: Optional[str] = None, force: bool = False,
  680. ) -> CodexResetRedeemResult:
  681. """Redeem one banked Codex rate-limit reset credit (`/usage reset`), mirroring the Codex CLI picker: GET usage →
  682. guard (a reset restores the WHOLE 5h + weekly allowance, and the backend's own ``nothing_to_reset`` guard is
  683. less clear) → POST consume with a fresh UUID ``redeem_request_id`` and no ``credit_id`` (the backend picks the
  684. next credit). Never raises: every failure returns a result."""
  685. import uuid
  686. try:
  687. token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
  688. except Exception:
  689. return _unavailable("No Codex credentials available. Run `hermes auth` to sign in with your ChatGPT account.")
  690. redeem_request_id = str(uuid.uuid4())
  691. try:
  692. for attempt in range(2):
  693. usage_url, _credits_url, consume_url = _codex_backend_urls(resolved_base_url)
  694. headers = _codex_headers(token, account_id)
  695. try:
  696. with httpx.Client(timeout=15.0) as client:
  697. usage_resp = client.get(usage_url, headers=headers)
  698. usage_resp.raise_for_status()
  699. payload = usage_resp.json() or {}
  700. available = _codex_banked_resets(payload)
  701. refused = _codex_reset_guard(payload, available, force)
  702. if refused is not None:
  703. return refused
  704. consume_resp = client.post(
  705. consume_url, headers={**headers, "Content-Type": "application/json"},
  706. json={"redeem_request_id": redeem_request_id},
  707. )
  708. consume_resp.raise_for_status()
  709. body = consume_resp.json() or {}
  710. break
  711. except httpx.HTTPStatusError as exc:
  712. if exc.response.status_code != 401 or attempt > 0:
  713. raise
  714. try:
  715. token, resolved_base_url, account_id = _resolve_codex_usage_credentials(
  716. base_url, api_key, force_refresh=True,
  717. )
  718. except Exception:
  719. # Refresh token dead too: the 401 hint (re-login) is the actionable message.
  720. raise exc from None
  721. except httpx.HTTPStatusError as exc:
  722. code = exc.response.status_code
  723. if code in (401, 403):
  724. return _unavailable(f"Codex backend rejected the request (HTTP {code}). Reset credits require ChatGPT-account "
  725. "(OAuth) auth — run `hermes auth` and sign in with your ChatGPT account.")
  726. return _unavailable(f"Codex backend error (HTTP {code}) — try again shortly.")
  727. except Exception as exc:
  728. return _unavailable(f"Could not reach the Codex backend: {exc}")
  729. return _codex_reset_outcome(body, available)
  730. def _fetch_anthropic_account_usage(
  731. base_url: Optional[str] = None, api_key: Optional[str] = None
  732. ) -> Optional[AccountUsageSnapshot]:
  733. # An explicit api_key (live agent / per-credential pool read) must not be shadowed by
  734. # the ambient OAuth singleton: fetch_account_usage(base_url, api_key) promises to
  735. # report THAT credential's usage. An API key answers the OAuth usage endpoint with
  736. # 401, so only an OAuth-shaped token reaches the fetch.
  737. explicit = str(api_key or "").strip()
  738. token = explicit or (resolve_anthropic_token() or "").strip()
  739. if not token:
  740. return None
  741. if not _is_oauth_token(token):
  742. return _snapshot("anthropic", "oauth_usage_api", [], [],
  743. unavailable_reason="Anthropic account limits are only available for OAuth-backed Claude accounts.")
  744. headers = {"Authorization": f"Bearer {token}", "Accept": "application/json", "Content-Type": "application/json",
  745. "anthropic-beta": "oauth-2025-04-20", "User-Agent": "claude-code/2.1.0"}
  746. payload = _get_json("https://api.anthropic.com/api/oauth/usage", headers, timeout=15.0)
  747. windows = _usage_windows(
  748. payload, (("five_hour", "Current session"), ("seven_day", "Current week"), ("seven_day_opus", "Opus week"),
  749. ("seven_day_sonnet", "Sonnet week")), "utilization", "resets_at", fraction=True,
  750. model_scoped={"seven_day_opus", "seven_day_sonnet"},
  751. )
  752. details: list[str] = []
  753. extra = payload.get("extra_usage") or {}
  754. used_credits, monthly_limit = extra.get("used_credits"), extra.get("monthly_limit")
  755. if extra.get("is_enabled") and _is_num(used_credits) and _is_num(monthly_limit):
  756. details.append(f"Extra usage: {used_credits:.2f} / {monthly_limit:.2f} {extra.get('currency') or 'USD'}")
  757. return _snapshot("anthropic", "oauth_usage_api", windows, details)
  758. def _fetch_openrouter_account_usage(base_url: Optional[str], api_key: Optional[str]) -> Optional[AccountUsageSnapshot]:
  759. runtime = resolve_runtime_provider(requested="openrouter", explicit_base_url=base_url, explicit_api_key=api_key)
  760. token = str(runtime.get("api_key", "") or "").strip()
  761. if not token:
  762. return None
  763. normalized = str(runtime.get("base_url", "") or "").rstrip("/")
  764. headers = {"Authorization": f"Bearer {token}", "Accept": "application/json"}
  765. with httpx.Client(timeout=10.0) as client:
  766. def _data(path: str) -> dict:
  767. resp = client.get(f"{normalized}/{path}", headers=headers)
  768. resp.raise_for_status()
  769. return (resp.json() or {}).get("data") or {}
  770. credits = _data("credits")
  771. try:
  772. key_data = _data("key")
  773. except Exception:
  774. key_data = {}
  775. balance = float(credits.get("total_credits") or 0.0) - float(credits.get("total_usage") or 0.0)
  776. details = [f"Credits balance: ${max(0.0, balance):.2f}"]
  777. windows: list[AccountUsageWindow] = []
  778. limit, limit_remaining, usage = key_data.get("limit"), key_data.get("limit_remaining"), key_data.get("usage")
  779. limit_reset = str(key_data.get("limit_reset") or "").strip()
  780. if _is_num(limit) and float(limit) > 0 and _is_num(limit_remaining) and 0 <= float(limit_remaining) <= float(limit):
  781. limit_value, remaining_value = float(limit), float(limit_remaining)
  782. detail_parts = [f"${remaining_value:.2f} of ${limit_value:.2f} remaining", *([f"resets {limit_reset}"] if limit_reset else [])]
  783. windows.append(AccountUsageWindow(label="API key quota", used_percent=((limit_value - remaining_value) / limit_value) * 100,
  784. detail=" • ".join(detail_parts)))
  785. if _is_num(usage):
  786. usage_parts = [f"API key usage: ${float(usage):.2f} total"]
  787. for key, label in (("usage_daily", "today"), ("usage_weekly", "this week"), ("usage_monthly", "this month")):
  788. value = key_data.get(key)
  789. if _is_num(value) and float(value) > 0:
  790. usage_parts.append(f"${float(value):.2f} {label}")
  791. details.append(" • ".join(usage_parts))
  792. return _snapshot("openrouter", "credits_api", windows, details)
  793. _USAGE_FETCHERS: dict[str, Callable[[Optional[str], Optional[str]], Optional[AccountUsageSnapshot]]] = {
  794. "openai-codex": _fetch_codex_account_usage, "anthropic": _fetch_anthropic_account_usage,
  795. "openrouter": _fetch_openrouter_account_usage,
  796. }
  797. # Picker per-credential variants: same parsers/fetch shape, but a failure is never repaired by
  798. # rotating/refreshing a credential (see ``fetch_account_usage(read_only=True)``).
  799. _READ_ONLY_USAGE_FETCHERS: dict[str, Callable[[Optional[str], Optional[str]], Optional[AccountUsageSnapshot]]] = {
  800. "openai-codex": _fetch_codex_account_usage_read_only,
  801. }
  802. # Wall-clock bound on a plugin profile's ``fetch_account_usage`` hook. The built-in fetchers above carry
  803. # their own httpx timeouts; a plugin hook is arbitrary code, and the gateway/TUI ``/usage`` paths await
  804. # this function with no deadline of their own (only the CLI wraps it in a 10 s future), so the bound
  805. # lives here where every surface shares it.
  806. PLUGIN_USAGE_HOOK_DEADLINE_S = 10.0
  807. def _call_plugin_usage_hook(profile, base_url: Optional[str], api_key: Optional[str]) -> Optional[AccountUsageSnapshot]:
  808. """Run the profile hook under the shared deadline; past it → None. Exceptions re-raise in the
  809. caller so ``fetch_account_usage`` fails open without a worker-thread traceback on ``/usage``."""
  810. from agent.deadline import run_bounded_sync
  811. from providers.base import ProviderProfile
  812. if type(profile).fetch_account_usage is ProviderProfile.fetch_account_usage:
  813. return None # base no-op: no thread to spawn
  814. bounded = run_bounded_sync(
  815. lambda: profile.fetch_account_usage(base_url=base_url, api_key=api_key),
  816. PLUGIN_USAGE_HOOK_DEADLINE_S, label="plugin-account-usage")
  817. return None if bounded.timed_out else bounded.value
  818. def fetch_account_usage(
  819. provider: Optional[str], *, base_url: Optional[str] = None, api_key: Optional[str] = None,
  820. read_only: bool = False, identity_id: Optional[str] = None,
  821. ) -> Optional[AccountUsageSnapshot]:
  822. from agent.account_usage_cache import remember_account_usage
  823. slug = str(provider or "").strip().lower()
  824. # The picker's per-credential path resolves variants that never rotate/refresh a credential
  825. # on failure (Codex 401), so a read cannot repair or bench a pool entry it does not own.
  826. fetcher = _READ_ONLY_USAGE_FETCHERS.get(slug) if read_only else None
  827. if fetcher is None:
  828. fetcher = _USAGE_FETCHERS.get(slug)
  829. import time as _time
  830. started = _time.monotonic()
  831. try:
  832. if fetcher:
  833. snapshot = fetcher(base_url, api_key)
  834. else:
  835. from providers import get_provider_profile
  836. profile = get_provider_profile(slug)
  837. snapshot = _call_plugin_usage_hook(profile, base_url, api_key) if profile else None
  838. except Exception:
  839. return None
  840. # Every fetch (``/usage``, the per-turn ``session.usage``) keeps the picker's cache current.
  841. # A per-credential fetch is remembered under its account slot only; the provider-wide fetch
  842. # keeps both the legacy gauge slot and (when the fetcher identifies the account) that
  843. # account's slot current.
  844. remember_account_usage(provider, snapshot, identity_id=identity_id, base_url=base_url,
  845. started_monotonic=started)
  846. return snapshot